GMU:Tutorials/Documentation/Tutorial How-To

From Medien Wiki
                                How to write an online tutorial

Tutorials are one main reason the Medienwiki exists, but not everything is as well documented as they should be. So in this tutorial i want to explain what you can do to make it better.

Subject Matter

You should write about anything, but it helps if you're feeling passionate about you're project. You should also preferably wrote about something original, there are not that many projects online here but you should first check if no one else write about it yet.

You should use the Wiki to…

Show us what you have made

Show us how you made something

Show us how to do something

You shouldn't use it for…

Show us somebody else work

Try and sell something without basic understanding how you accomplished it

Write inappropriate things

You should preferably write in english if not otherwise stated in your course description, so that every foreign student has a chance to understand the things that you've made. Also you should watch your language, you don't need to write a scientific masterpiece of a research but you're Professor will still probably read it.

What kind of Tutorial should i do

Basically using the current version of the wiki only allows you to make a step by step instruction. You could also film what you're doing and setting up a link to the video into the wiki. (youll find a good guide for making a video tutorial here) The step by step tutorial consists of one step followed by some photos at a time. You could split it up like this:

Preparation

What you need for it

Start

Some small explanatory steps

End result with some photos or a video

Photos

For making a good online Tutorial its essential that you're taking good photographs. You should always try to make your own photos and illustrations of your work, cause the wiki isn't meant to be hosting content from content that you found on the internet. Use a proper scanner to digitalise drawings and schematics. You should also think of using a proper camera for taking photos of your work rather than quickly taking a snapshot with your mobile phone, you will thank yourself later for having your work properly documented. Make sure the image is sharp and the object is in focus use macro settings if you need to. Take photographs from different angles of your object and try to light your object even. You should use a white background for it and lots of daylight, if it isn't available try using a desk lamp. (you can also build you're own lightbox ) Take more photos than you need, you can upload them into a gallery function.

Structure

     Title

You need to be aware of the way your reader encounters your work. The first thing the reader sees is unfortunately just the title of the work and the description of the course it was made in. So you need to have a good catchy title that wakes up the readers interest.

Good title: How to make a ### to help you ###

Good title: Improve your ### by ### and ###.

Bad title: The Widget by Name!

Bad title: What everyone has been waiting for: the AWESOME PROJECT!!!!!

Bad title: Yet Another ……


    Top Picture

For the Top of your page choose a picture that shows your work in its best light. This is the first time the reader is going to encounter your work by actually seeing it, so it has to make a good impression.

    Instruction

Position an instruction underneath the top image. The instruction itself should be reasonably short, and doesn't need to include any details of how you made the project. Throw in a little history of how you came up with the project if you like. If the back-story is long, it might be worth a whole step to itself. Assuming the title and course description has persuaded the reader to start reading the next thing they see is a photo of your work and the instruction. This is the last chance to convince wavering readers to continue reading, so take a few minutes to get it right

    The Other Steps

Theres no rule how you want to structure your tutorial every tutorial/presentation differs from the other, but there are some essential steps you should keep in mind:

     Materials and Tools

Make a list to help others to get organised before rebuilding you're project in real or in they're minds especially if there are special uncommon items they need to borrow or buy.

     Preparation

For projects that have to do with electronics for example do you need to prepare something? Anti static mat, preheating your soldering iron, 3D printing some parts etc.

     How you made it

Make a step by step description of how you made and better take it slow. No one knows better what you've did than you yourself but for others it maybe isn't that easy to follow your lead.

    Tips 

Have you been confronted with some issues that were hard to figure out how to do but you solved it somehow using a clever trick. Then share it with you're readers they will be thankful about that.

    Further Ideas

Now after finishing your projecting and reflecting onto it while writing about it. Do you have plans for the future, do you think theres more potential in it or do you want to do something different than you did. You'll readers will be excited to hear about it especially if you've done some really vague project wich doesn't have an clear outline yet.

    Layout

There are some things you should mind using the wiki, it has some shortcuts for lay outing the text that you need to quote into you're text. Also theres a sidebar above the text window wich contains shortcuts for lay outing:

Screen Shot 2016-07-01 at 18.16.09.png

Writing bold

Writing cursive

Writing underlined

Linking a Website

Writing an Headline Text

Implementing an Image

Linking a file

Writing an formula

Ignore the wiki specific preset lay outing rules

Add a signature and a timestamp

Adding a line


You will find the option to upload images to the wiki on the left side underneath the Bold Headlines in the sidebar.

Screen Shot 2016-07-01 at 18.44.20.png

You can then choose a picture to upload from your PC but mind two things

1. Upload a .png file (.jpg files cant be uploaded to the wiki)

2. Compress your image as much as you can (the wiki wont show to big files either)


Performance Platform specific

The PC in the Performance lab is running Debian you can make a:

Screenshot using ctrl+ shift+ alt + s (wich will be saved in the images folder)

Screen recording alt+ cmd+ v (you can start and stop with this command. There is a red dot appearing in the Top bar of the Dektop to indicate that youre currently recording. The video will be saved in your video folder)