[RogueCoder]

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

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

1. Patience - Writing a high quality tutorial means writing, proof reading, modify, then repeat the process
   
2. Proper grammar - This does not mean perfect English, but stay away from meaningless abbreviations like plz, thx, rofl
   
3. 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, it's just 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

• Introduction
  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.
  
  
• Max length
  It can also be 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 personally I find it easier to read that way.
  
  
• Preview and saving draft
  Throughout the process it's also very smart to keep using the "Preview Post" button 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.
  
  You should also get used to the "Draft" button. By using this with regular intervals you won't risk losing to much of your work if you accidentally close your browser/tab, your connection dies or whatever.
  
  
• Text formatting
  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
  
  
• External resources and references
  When using external resources in your tutorials, you must always include the links for these resources in your tutorial. You should link to these resources throughout your tutorial.
  In addition to this, it can also be a good idea to add a "External resources / references" headline near the end. Here you can list all the same links together.
  It's not a bad thing to mention references. You might feel that you come across a person who's not able to write the tutorials yourself. Well, there's nothing wrong in getting help from others as long as you give the proper credits.
  
  If you have found tutorials that extends your own, don't be so proud that you leave it out. In the end, this will only hurt your readers. Especially the newcomers.
  All links to these types of articles and tutorials should be treated like the ones mentioned in the previous paragraph. Add the links throughout your tutorial, and separate headline named something similar to "Further reading"
  
  
• Document requirements
  When you are writing a tutorial that includes using specific tools you include both a link for download, and a link to a tutorial about the tool. This way the reader can pause your tutorial and understand what the tools you are using actually does.
  If a reader cannot fully understand ever aspect of the tutorial, (s)he will be left with a gap in their knowledge which it was your job as the author to fill. Either by writing a tutorial on the tool yourself, or link to some external resource.
  No matter which one you choose, it's your job to make sure that the reader fully understands what's going on everywhere in your tutorial. Not just the steps.
  
  
• Rule of thumb
  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

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.

-- End of tutorial --

Request for comments

Do you find the structure of the tutorial as it is now harder or easier to read? I personally find it easier to read when the lines does not go all the way, but I'm only one man. The majority should decide

Final words

I hope you found this helpful. If you have any suggestions or questions leave a comment and I will answer it to the best of my knowledge.