How To Write A Good Tutorial

[JGM]

How To Write A Good Tutorial

Greetings and welcome to my tutorial on "how to write a good tutorial"! Now you must be thinking "well how hard can it be?". The simple answer is not very or very depending on how you look at it, you see there is a huge difference between a tutorial and a good tutorial. I have been commended on more than one occasion for my ability to explain things in such a way that is easy to understand and easy to follow, now again you might be thinking "well how hard can that be?". The actuality of it is that it can be very hard, many people who write tutorials forget who they are talking to when they write their tutorials so very often you will find them using technical jargon and assuming that you know what they are talking about. How can you know what they are talking when you are trying to find a tutorial on whatever it is you are looking for? Simply put it is like trying to teach somebody the offside rule in football when they have no knowledge of the sport at all.

In my time I have numerous tutorials and for the most part with great success, so what is my secret? Well it is quite simple really... think about what you are doing! Anybody can just explain something to somebody but getting them to understand it is a whole different skill and with any luck this tutorial will help to teach you that skill. Below are a few headings for each section of this tutorial and each one will be explained as we go along, so lets get going...

Section 1 - The Concept

So you have decided to write a tutorial on your given topic whatever it may be, now you need to ask yourself "how much about this do I really know?". If the answer to that is not much then you have a few options;

1. Learn As Much As You Can - Writing a tutorial about something you don't really know is a waste of time for both yourself and the people who would read the tutorial. Go and do your research and learn about whatever it is that you want to write about, trust me your readers will thank you for it.
2. Change Topic - You can of course change your topic to something you do actually know about.

Try to make the tutorial about something that you yourself have done or had to do in the past or even currently doing, by doing so you can talk/write from a perspective of experience which in the real world goes a long long way.

Section 2 - The Draft

Now is the time to fire up your favourite text editor or even go old school and use pen and paper! Think back to your school days and when you wrote an essay or something similar you always wrote a draft in order to get everything right? Do the same for a tutorial, by doing so you can properly organise everything so that everything makes sense when it is read out loud (actually do this yourself but more on this later). Many many times have I seen tutorials that jump and skip all over the place so that eventually you have no idea on what to do or where to go next, avoid this by keeping a few simple things in mind;

• Baby Steps - The first thing you should remember/assume is... everybody is an idiot! Now before people start there is a perfectly logical reason for this, now most of you who are reading this will be into forums and similar things and how many times have people asked you for help and you have tried to explain it to them and they just don't understand? Lots I should imagine! Assume that everybody is like that from the start and your tutorial will cater for everybody newbies and experienced pro's alike.
• Structure & Organise - Writing a tutorial is a lot like writing a story in that a story has a start, a middle and an end. Structure your tutorial so one thing leads to the next step in a logical fashion and prevent people from having to back track through your tutorial to find the bit that corresponds to where they are now.
• Language - This for many people is a big problem, when most people write tutorials they use (as mentioned before) technical terms for all sorts of things which the average person might not have a clue about. Try to keep the technical side out as much as possible and if it has to be included then immediately follow it up with an explanation of what you just said and put it in lamens terms.
• Spelling & Grammar - I wish people would learn how to use spell checkers! Reading a tutorial that does not make sense due to spelling mistakes is just asking for trouble. Grammar is also very important, many people write/type how they talk so many grammatical errors occur. Avoid this by proof reading your tutorial out loud to yourself and others if you can, anybody will do be it a friend, husband/wife etc. You will quickly realise just how much of your writing does not make proper sense.
• Smilies, Emoticons and Text Speak - Avoid them all at all costs! Smilies and emoticons look nice and are amusing most of time but in a tutorial (especially detailed ones) they are extremely annoying and irritating. Text speak is even more annoying, always use proper words rather than shortening things e.g. lol, rofl, lmao, u (you), r (are) etc. Acronyms are fine though but make sure to explain them for example; "my POV (Point Of View) is that this..." by doing this you can then re-use it later and people are familiar with it already so you don't have to explain it again.
• A Picture Is Worth 1,000 Words - Be careful with the use of pictures in your tutorial, yes by all means use them but don't fall in to the trap of just using images to explain everything since most of the time it can be hard to see how to get from picture to the next or one stage to the next. Split images up with words which clearly explain what is being shown (remember to watch the technical jargon).
• Using Coloured Text - Be careful when doing this, without realising it many people are partly colour blind (myself included), the common one for this is what is known as the Red/Green group. This does not always mean that they can't see the colours Red or Green, myself for example can see both of these colours fine but I struggle with shades of colours such as dark brown and black look the same as does dark blue and purple. Be mindful that your tutorial can potentially be seen by anybody.

Section 3 - The Edit

Once your draft is finished you are still not ready to publish your tutorial just yet, make sure to do the proof read of the entire tutorial without skipping a single part. By doing so you can check for grammatical mistakes and correct spelling errors too (don't forget that spell checker!). While proof reading you may also find that you have missed a step or a bit of information about something so now is the time to make sure you add it in to make your tutorial the best it can be.

Section 4 - The Last Hurrah!

With everything done you are practically ready to publish the tutorial, just make sure you have not forgotten anything and publish the tutorial!

Well there you have it folks my winning formulae, I have used this system for a long time and it has never failed me yet so I hope you can learn from it, find it useful and of course... write better tutorials for everybody!

JGM.

JGM Reviewed by JGM on 24th Nov 2011. How To Write A Good Tutorial How To Write A Good Tutorial Greetings and welcome to my tutorial on "how to write a good tutorial"! Now you must be thinking "well how hard can it be?". The simple answer is not very or very depending on how you look at it, you see there is a huge difference between a tutorial and a good tutorial. I have been commended on more than one occasion for my ability to explain things in such a way that is easy to understand and easy to follow, now again you might be thinking "well how hard can Rating: 5

[Rox]

awesome tips mate just in time for my new tut blog

[Drag]

A tutorial on how to write a tutorial. Epic! Good job mate.

- Peter

[foxman]

Good post, bit too long. But Thanks for the time you spent creating the Post.

Best.