Writing a tutorial
When you are writing an informative piece that is designed to teach people there are a few guidelines that may help. I hope that this article will give you ideas on how to improve your ability to write tutorials and therefore improve the ability of your tutorials to help people.
Objective: It is wise when writing a tutorial to have a short introduction that tells the user the objective of the piece and give a brief outline of the method you plan to teach.
Formatting: Clear formating can make or break a tutorial. Split the text into paragraphs. If you are giving short sequential instructions use bulletpoints. Here is an example of what I mean.
Bad formatting
To make a cup of delicious sweet tea you need to do a few simple things. Fill your kettle with enough water but don't exceed it's maximum capacity and then you want to put it on to boil. In the time it takes to boil you will gather and prepare your cup for the hot water as well as getting the other things you need to make your tea extra nice. Take the milk out of the fridge, the cup out of the cupboard, teabags out from the press and the sugar jar accross from the kitchen table. Now, when your water is boiled you put the teabag in the cup then pur in the hot water. Now that the hot water is added you stir it with a spoon and brew to your liking. Next you add milk and sugar to taste and remove the teabag and dispose of it. Tea can also be enjoyed with buiscuits if you want.
Good Formatting
This Tutorial will teach you how to make a cup of tea.
You will need:
- A kettle
- Sugar/Milk (if desired)
- Teabags
- Water
- A cup & a teaspoon
Procedure:
- Put the kettle on to boil enough water without exceeding it's capacity.
- Place the teabag in the cup.
- When the water is boiled pour it into the cup.
- Using the spoon to stir, brew to a desired strength before removing and disposing of the teabag.
- Add milk and sugar to taste.
Have some nice biscuits with your tea to improve the experience.
As you can see the second tutorial is much clearer, gives an objective and procedure as well as a helpful tip. The same information is in the first tutorial but is harder to find. By using good formating you increase the chances of finishing up with the desired end product. In this case, a cup of tea.
Tone: The tone of your written piece can be whatever you desire. However, while some people, myself included, find humor and analogy lighten the mood of a tutorial and make it more readable some people find them distracting and detracting. It is best to find a balance. Don't make your writing too clinical but make sure that the reader won't get lost either.
Images: Images are a great addition to a tutorial but there are a few things to remember.
- Don't go overboard. A picture says a thousand words so a thousand pictures...
- If you need to use a large amount of imagery then it is a good idea to split the tutorial over a few pages
- Only use images that are necessary and resize and crop them to fit the purpose
- Video is a great medium as well but make sure that it is cut together properly and dialogue is clear. If you are using YouTube use annotations to show the button commands you use. "E", "D", "C" and "P"all sound pretty similar when audio is compressed!
Planning: The final thing I'm going to mention is planning. It can help to sit down prior to writing a tutorial to make a spider diagram or mind map about what you want to cover. Writing up draft coppies and then re-reading them a bit later or getting someone else to read it. You are much more likely to be able to spot little mistakes or problems by doing this.
