How to write high quality tutorials

How to write high quality tutorials - Printable Version

+- Sinisterly (https://sinister.ly)
+-- Forum: General (https://sinister.ly/Forum-General)
+--- Forum: The Lounge (https://sinister.ly/Forum-The-Lounge)
+--- Thread: How to write high quality tutorials (/Thread-How-to-write-high-quality-tutorials)

Pages: 1 2 3

How to write high quality tutorials - RogueCoder - 06-15-2013

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, 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 Smile

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.

-- 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 Smile

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.

RE: How to write high quality tutorials - cracker_team_mybb_import7369 - 06-15-2013

Wow man i was impresed by what you wrote. This is amazing. Keep up the good work and also newbies should learn by your thread. Great work done by you.

RE: How to write high quality tutorials - RogueCoder - 06-15-2013

(06-15-2013, 11:50 AM)Cracker_Team Wrote: Wow man i was impresed by what you wrote. This is amazing. Keep up the good work and also newbies should learn by your thread. Great work done by you.

Thanks man! Really appreciate your feedback Smile

RE: How to write high quality tutorials - Psycho_Coder - 06-15-2013

This morning I started making this tutorial and saved it as a draft as it wasn't complete and now I am seeing that you have posted it. He He he :lol:

However this is a cool guide and will serve as a guideline for those newbies who are willing to dedicate themselves to HC by sharing their knowledge. But I have some suggestions.

In the steps 1, steps 2 and steps 3 please use lists in your thread as these are notable points and these look more appealing.

In step 3

Spoiler:Quote: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.

Quote:

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.

The above two points are one complete points but however there are newlines that have appeared between the words so remove them therefore they should be like.

Spoiler:Quote: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.

Quote: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.

Similar thing is to be done with the use formatting part

Leave the font size to normal (but this is not a major factor, you can ignore it)

After every header or title leave a line gap and it makes it more appealing.

I prefer justifying the whole tutorial as it looks better documented

You might also include that if the image sized are very large then they must be included within spoilers and the spoilers are to be given a title.

You can also include that when making a tutorial one should save thread as draft after an interval so that data is not lost even if the tab gets closed by mistake also it will help to divide the work of making a tutorial,I use this technique very often.

These are suggestions and comments on your way of posting the thread. Since this thread is about proper posting so this particular post must be perfectly designed.

Thanking you,
Sincerely,
Psycho_Coder

RE: How to write high quality tutorials - RogueCoder - 06-15-2013

(06-15-2013, 01:11 PM)Psycho_Coder Wrote:
This morning I started making this tutorial and saved it as a draft as it wasn't complete and now I am seeing that you have posted it. He He he :lol:

However this is a cool guide and will serve as a guideline for those newbies who are willing to dedicate themselves to HC by sharing their knowledge. But I have some suggestions.

In the steps 1, steps 2 and steps 3 please use lists in your thread as these are notable points and these look more appealing.

In step 3

Spoiler:
Quote: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.

Quote:
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.

The above two points are one complete points but however there are newlines that have appeared between the words so remove them therefore they should be like.

Spoiler:
Quote: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.

Quote: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.

Similar thing is to be done with the use formatting part

Leave the font size to normal (but this is not a major factor, you can ignore it)

After every header or title leave a line gap and it makes it more appealing.

I prefer justifying the whole tutorial as it looks better documented

You might also include that if the image sized are very large then they must be included within spoilers and the spoilers are to be given a title.

You can also include that when making a tutorial one should save thread as draft after an interval so that data is not lost even if the tab gets closed by mistake also it will help to divide the work of making a tutorial,I use this technique very often.

These are suggestions and comments on your way of posting the thread. Since this thread is about proper posting so this particular post must be perfectly designed.

Thanking you,
Sincerely,
Psycho_Coder

Thanks for sharing your opinion and suggestions on this thread Smile

This is exactly the type of feedback I was hoping for Smile

I will look into each point and modify it accordingly

RE: How to write high quality tutorials - zomgwtfbbq - 06-15-2013

Good job, maybe this will be the end of the so called tutorials with only 10 sentences.

RE: How to write high quality tutorials - soh_cah_toa - 06-16-2013

I would probably argue that the most crucial step in the writing process is step two. Planning makes all the difference. It allows you to organize the structure of what you intend to explain. You can see what needs to come first, what a good follow up might be, at what point an example is needed, when to move on to more advanced things, how to conclude, etc.

By planning the layout ahead of time, sometimes I'll notice that it's way too much for a single discussion. I'll decide to either break it up into multiple posts or cut out the flab without compromising the quality. You can easily identify when someone hasn't spent time planning their material.

When I find myself at step four, I also make sure to check if I've made good use of paragraphs. Reading long paragraphs can be a strain and slows down the reader when going back to something earlier. If I never did any sort of proofreading, I'd look like a damn fool. Mistakes are inevitable and it's important to catch them. Otherwise, you come off as being lazy and unconcerned with how you're perceived by others.

So thanks for the high quality tutorial on writing high quality tutorials. Wink

RE: How to write high quality tutorials - Psycho_Coder - 06-16-2013

@shp0ngl3 Its good to see that you took my suggestions and edited the thread and now its looks very good. Good work. But I think you won't mind if I add some more comments as you're asking for it.

Points that you might interest you to include them in your thread :-

You have left a line gap just as I told you earlier but you did that for steps 1,2 aqnd 3 only, what about step 4 and step 5. You must leave a line gap there too.
You have said that one must include keywords as headings which will give the reader an idea about what he/she is going to learn, and this is 100% correct. I want to add that you should tell that they must at first include a heading with large font that says "Tutorial Objectives", as I feel this would be more appropriate. I have always added these in my tutorials.
One who is making an HQ tutorials needs a lot of resources and one has to take many references and you have mentioned this too, but similar to the previous point one should make a headline "References Taken", also mentioning the references is not bad as many new users feel that if they do give references then it would mean that they know nothing which is not true and as a result its called Leeching at the end by others. SO under that heading he must include all the references from where he took help. Also, he can add another heading "Further Reading" which would help the reader to get some more detailed information on that subject as it is not possible for one to include everything. I personally feel the any HQ tutorial is just to get you started.
An HQ tutorial means that the reader must have some per-requisites for better understanding. For example, take your walkathrough's if a user doesn't knows about the tools and what they do then its not worth reading and just a waste of time as his/her knowledge will get bounds. So one must include some links in the introduction part for if there are any per-requisites that the user must know.
If your using some tools in your HQ tutorial then one must provide the download links for those tools.
Suppose if someone is giving difference between two topics then they should use a table to do that as its more appealing and looks good and clean and easily understandable.

Sample difference :-

[table]
[row]
[cell] Differences between C and C++[/cell]
[/row]
[/table]
[table]
[row]
[cell] C[/cell]
[cell] C++[/cell]
[/row]
[row]
[cell]C follows the procedural programming paradigm[/cell]
[cell] C++ is a multi-paradigm language(procedural as well as object oriented) [/cell]
[/row]
[row]
[cell]In C the data is not secured [/cell]
[cell]the data is secured(hidden) in C++.This difference is due to OOP features like Data Hiding which are not present in C. [/cell]
[/row]
[row]
[cell]C uses the top-down approach [/cell]
[cell]C++ uses the bottom-up approach( the base elements are first formulated which then are linked together) [/cell]
[/row]
[row]
[cell]C is function-driven [/cell]
[cell]C++ is object-driven [/cell]
[/row]
[row]
[cell] Structures cannot contain functions in C.[/cell]
[cell] Functions can be used inside a structure[/cell]
[/row]
[row]
[cell]C does not support Exception Handling [/cell]
[cell]C++ supports Exception Handling [/cell]
[/row]
[row]
[cell]C does not have NAMESPACE[/cell]
[cell]C++ supports Exception Handling [/cell]
[/row]
[row]
[cell]C is a Middle-level Language [/cell]
[cell]C++ is a High-Level Language [/cell]
[/row]
[/table]

I hope this helps a byte.

Thank you,
Sincerely,
Psycho_Coder

RE: How to write high quality tutorials - RogueCoder - 06-16-2013

@Psycho_Coder, thanks for your great feedbacks man! I do not have a good defense for why step 4 and 5 doesn't have a gap Smile

Only one would be, it was 3am when I was modifying :lol:

I will go through your points and add your suggestions Smile

RE: How to write high quality tutorials - Psycho_Coder - 06-16-2013

(06-16-2013, 08:31 AM)shp0ngl3 Wrote: @Psycho_Coder, thanks for your great feedbacks man! I do not have a good defense for why step 4 and 5 doesn't have a gap Only one would be, it was 3am when I was modifying :lol:

I will go through your points and add your suggestions

No problem. But No excuses please, time doesn't matter. However you must get to bed by that time its bad for health to be awake late nights (My father says this)

From last 3 days I am going to bed to sleep at 5:15 am in the morning :lol: