How to write a high quality tutorial 06-02-2013, 11:49 PM
#1
![[Image: x9y38Wr.png?1?8661]](http://i.imgur.com/x9y38Wr.png?1?8661)
How to write high quality tutorials
The quality of the tutorials being posted here is usually very high, but we see that tutorials that is written by some newcomers are not very high quality.
So I've written this as an effort to further increase the level of quality of the tutorials in this community, so that we get even less 10 single-liner step tutorials that is hard to understand.
It's a large difference between this
Quote:Step 1: Goto website login
Step 2: Enter x' or 1=1 # in the username
Step 3: Click login button
and a high quality sql injection tutorial. Even though those three lines does explain enough for someone to know what to do, it's not high quality.
The difference between a low and high quality post is that high quality posts explains what is going on under the hood throughout the process.
This leaves the reader with and understanding that makes it easy to continue to build on this knowledge.
To write some text that describes a process is easy, but if you want to write a high quality tutorial with real educational value you will need
- Patience - Writing a high quality tutorial means writing, proof reading, modify, then repeat the process
- Proper grammar - This does not mean perfect English, but stay away from meaningless abbreviations like plz, thx, rofl
- Good structure - Use paragraphs, images, spoilers, colors, etc to create a structure that is easy on the eye and has good readability
Step 1: Introduction
All tutorials should start with a proper introduction that summarizes what the tutorial is about. The reason why this is important is because it prepares the reader on what information (s)he's about to take in.
It's also important to limit the length of the introduction. Keep it short and to the point. Remember, the introduction is to give the reader a quick glimpse into the future, to make a decision whether the tutorial is of any interest.
Step 2: Planning
To write a high quality tutorial you should prepare before you start writing. Don't be shocked if you spend 4 hours on a single tutorial, this of course depends on the type of tutorial you are making.
The first thing you should consider is the structure and sections of the tutorial. Create a rough draft with some keywords for the introduction, add headlines followed by keywords about the content.
Then you should gather any images, codes, quotes, external source links, etc that you are going to use in the tutorial and add them to the tutorial. Don't spend to much time on making the locations perfect,
it's just a rough draft. Now that you have a rough overview of the tutorial it's time to start writing the actual content of the tutorial.
Step 3: Writing the tutorial
Start with the intro, but don't put too much time in it. Start writing below the keywords, and don't remove them until you have an introduction that you can consider as the final result. Keep in mind that
the introduction don't have to be perfect right away. It's often needed to modify this while writing the tutorial. It's also a good thing to keep a max line length. Doing this might not appear to be so significant,
but from my personal experience I find it very hard to read lines that goes all the way to the end of the screen. This might be because I am dyslectic, but nonetheless it will make the content much more readable.
Throughout the process it's also very smart to keep using the "Preview Post" actively. By doing this you will get early pointers on if it's going in the direction you want, or if something has to be changed.
The sooner you become aware of images that needs to be relocated, bad structure, wrong colors, etc, the less time you will spend fixing this later into the process. If you wait until the end you might find
out that it looks messy, and you will have to edit everything as a whole, instead of taking each part as you write them. It also helps to get a complete overview of the content.
Personally I prefer to check after every paragraph. This might be a bit excessive, but it's a habit, and I find this method very efficient.
Use text formatting! Don't be afraid of using bold, italic and underline. As long as you use it in the right places it raises the educational experience for the reader. When used correctly,
the readers brain will automatically interpreted this as something noteworthy and it will be easier to remember. It kind of works in the same way as the blocks of notes in school text books.
Just make sure that you don't overdo it. This will make to much of the content stand out, and you might end up with something like a DoS attack on the brain
Do not rush it. Haste equals waste
If you need to do something else, just save the draft and continue when you have time.Step 4: Proof reading and spell checking
When you have completed the tutorial and everything looks good the final stage is to read through the entire tutorial from top to bottom looking for spelling errors, bad use of punctuation's, etc.
Spelling errors are an easy task these days since the browsers are highlighting misspellings
All you need to do is to right-click the highlighted words and select the proper translation from the list.Step 5: Encourage participation
Just because you are the author of the tutorial, you should never consider yourself a guru or the only one knowing anything about the topic. Encouraging the community to participate is a great way to learn even more.
Round up your tutorial by asking a few questions and talk directly to the reader.
Example
Quote:Thanks for reading my tutorial. If you feel I have left out something, or you think you know a more efficient way of getting the job done please do not hesitate to leave a comment.
If something was unclear or you got stuck during this tutorial let me know and I will help you the best I can.
![[+]](https://sinister.li/images/modern/collapse_collapsed.png)
