Tips for writing an effective tutorial

Writing a development tutorial requires a few more considerations in comparing to writing a regular article. Readers would have to follow the steps, read code, view demos or examine a picture explaining some feature. Here are several tips that might help you write more efficient tutorials.

I won't explain here how important it is to choose the right subject, good title and other things that you can read in many other articles about writing for the web. I will focus on things that are specific for tutorials. Alhtough some of these tips can be applied to any type of article, they are even more significant in tutorials. For more general guidelines on how to write for the web, especially from usability perspective, I recommend you read Writing for the Web series of articles.

1. Make it short but to the point

Let's be honest, a very few readers will read the entire tutorial. As with any content on Web they will scan the content instead of reading it. Only if they find an interest in what you are showing they will read. Avoid long paragraphs and series of paragraphs without code snippets or images. Also avoid describing each tiny thing user should do, but rather show the key points in the path to tutorial completion. However, you shouldn't omit anything important. For example, it is important to explain how an element will be animated with jQuery, but it is completely unnecesary to explain and show each line of HTML structure or CSS code used in tutorial.

2. Explain each task shortly

You should be able to explan each task in a few simple sentences. Einstein said "If you can't explain it simply, you don't understand it well enough". Imagine what would readers think of your knowledge of the subject and how they would understand it. If you make it too long, go back and rewrite it.

3. Break it into logical steps

This will help users read and follow a tutorial more easily, and get back to a specific step if they need to. Each step should contain several tasks after which reader will be able to actually see some result.

Build Internet tutorials are easy to follow. Each tutorial is divided into logical steps and each step is easy to understand.

4. Include code but don't over do it 

If you have code to show, do it but don't paste the entire demo in the tutorial. No one will be interested in reading couple of screens of markup. Show only key snippets. You should, for example, show just a few fields of a large web form to enable readers to get the big picture of what you are showing. Readers who are interested in the full code will check out the demo or download source code. Which bring us to the next tip.

5. Provide a demo

Always try to provide a demo. I tested several of my previous tutorials and tests showed that nearly 70% of all readers view the demo. Many of them (63%) view demo first and if they like what they see they read the tutorial. Don't forget to add a link to the tutorial on all demo pages so that readers can easily go back.

The screenshot above is taken from one of the tests I mentioned. The link hidden behind clicks is a link to the demo page and it shows how important it is to include a demo in a tutorial.

6. Visualize the most complex tasks

You can also provide images explaining the most complex taks or steps. When readers see a demo they will understand how it works, but they will understand how it is made only if they read the demo or see the image explaining the process of creation. Such images also help readers visualize some steps or the entire tutorial.

In one of my previous tutorials, Create Vimeo-like top navigation I provided two images that help users visualize the most complex tasks.

In his latest tutorial How to Add a Fixed Position Banner to a Website, Steven Snell uses images effectively. He provides several live examples of the feature he decomposed.

7. Always provide source code

Some readers will like to have the code from the tutorial offline. This way they can examine the code even if they are not able to access your tutorial for whatever reason. You should compress your files and give a meaningful name to the compressed file. Same applies to all other files. You should also add a link to the tutorial in your demo pages so that reader can easily go back if necessary.

8. Have download and demo links in prominent position

This is one of the most important aspects in web dev tutorials. As I mentioned before, a lot of users will take a look at the demo first and that's why it is important to place a link to the demo at the top of the article and make it prominent. The usual position is below a short introduction and/or image but before the first step in the tutorial. I also tested three different versions of the same tutorial.

• Tutorial with a prominent link to demo page at the top of the tutorial
• Tutorial with a plain link to demo page at the top of the tutorial
• Tutorial with a link to demo page placed at the end of the tutorial

The results I mentioned in tip #5 refer to the first version. Other two had significantly lower number of users that viewed the demo, which is somewhat expected.

The exception is the case when you have more than one demo; in which case, you should place links to each demo just below the heading of a section describing it.

3 Easy and Fast CSS Techniques for Faux Image Cropping tutorial on CSS Globe has three demos.

9. Join the discussion

Once you publish a tutorial your job is not done. Readers will have different opinions about your work. They might criticize the way you created something or they might have some suggestions and improvements. Answer those comments. By joining the discussion you will send your readers a message that you care about their opinion and that your tutorials are really there to help.

You will also learn more and be able to see a specific problem from different angles. After all, you started it all by posting the tutorial ;)

10. Update the tutorial if needed

If you made a mistake or if someone comes up with an improvement, you should update your tutorial. It will give satisfaction to readers that noticed issues and also give motivations for others to actually read your tutorials and comment on them. Not necessarily, but you can also give credits to people who spotted issues.

Marco updated his tutorial A fancy Apple.com-style search suggestion with PHP4 version of the code provided by one of his readers

Your tips?

Would you add/change anything? What annoys you the most when you read tutorials? What do you like the most?