Skip to main content

Write a Good Tutorial

Tutorials are practical lessons which introduce users to a new software or feature. Your tutorial should be learning oriented, and it should only get users started, not turn them into experts. The following article describes a few keys to a good tutorial.

Tutorial Template

The IOTA Wiki hosts a tutorial template.

Get the Users Started

Unlike a how to guide, a tutorial needs to start at the very beginning. Your tutorial should provide every single step needed to achieve the goal. Users can skip whatever parts they deem unnecessary. You should list any prerequisites right at the beginning so users can prepare anything they need before starting.

Set a Clear Goal and Milestones

Your tutorial should have a clear goal, and possibly some milestones along the way. The users should be able to know what they are going to achieve right from the start, so they know what to expect to learn. Since your tutorial will likely have many steps, you should tell the user exactly what to expect with milestones.

You should not give the users many options. Your tutorial should only follow a happy path. If they want a full list of options they can follow a how to guide, or look up the reference.

Milestones

Users will need to follow several steps to achieve the tutorial's goal. You should only describe these steps, and avoid going into lengthy explanations or abstractions. If you need to explain something, you should only introduce the topic and link to a full length explanation if needed. You should provide expected outputs, and responses so the users know if they are being successful.

Test Your Tutorial

Every step in your tutorial should work every single time. It is your job to guide the user through a happy paths which must work every time. If you need a specific version of any software you should state this in the prerequisites.