Skip to main content

​
Allow the user to learn by doing

In the beginning, we only learn anything by doing - it’s how we learn to talk, or walk. In your software tutorial, your learner needs to do things. The different things that they do while following your tutorial need to cover a wide range of tools and operations, building up from the simplest ones at the start to more complex ones.

​
Get the user started

It’s perfectly acceptable if your beginner’s first steps are hand-held baby steps. It’s also perfectly acceptable if what you get the beginner to do is not the way an experienced person would, or even if it’s not the ‘correct’ way - a tutorial for beginners is not the same thing as a manual for best practice. The point of a tutorial is to get your learner started on their journey, not to get them to a final destination.

​
Make sure the tutorial works

One of your jobs as a tutor is to inspire the beginner’s confidence: in the software, in the tutorial, in the tutor and, of course, in their own ability to achieve what’s being asked of them. There are many things that contribute to this. A friendly tone helps, as does consistent use of language, and a logical progression through the material. But the single most important thing is that what you ask the beginner to do must work. The learner needs to see that the actions you ask them to take have the effect you say they will have. If the learner’s actions produce an error or unexpected results, your tutorial has failed - even if it’s not your fault. When your students are there with you, you can rescue them. If they’re reading your documentation on their own, you can’t, so you have to prevent that from happening in advance. This is without doubt easier said than done.

​
Ensure the user sees results immediately

Everything the learner does should accomplish something comprehensible, however small. If your student has to do strange and incomprehensible things for two pages before they even see a result, that’s much too long. The effect of every action should be visible and evident as soon as possible, and the connection to the action should be clear. The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment.

​
Make your tutorial repeatable

Your tutorial must be reliably repeatable. This is not easy to achieve: people will be coming to it with different operating systems, levels of experience and tools. What’s more, any software or resources they use are quite likely themselves to change in the meantime. The tutorial has to work for all of them, every time. Tutorials unfortunately need regular and detailed testing to make sure that they still work.

​
Focus on concrete steps, not abstract concepts

Tutorials need to be concrete, built around specific, particular actions and outcomes. The temptation to introduce abstraction is huge. It is after all how most computing derives its power. But all learning proceeds from the particular and concrete to the general and abstract, and asking the learner to appreciate levels of abstraction before they have even had a chance to grasp the concrete is poor teaching.

​
Provide the minimum necessary explanation

Don’t explain anything the learner doesn’t need to know to complete the tutorial. Extended discussion is important - just not in a tutorial. In a tutorial, it is an obstruction and a distraction. Only the bare minimum is appropriate. Instead, link to explanations elsewhere in the documentation.

​
Focus only on the steps the user needs to take

Your tutorial needs to be focused on the task at hand. Maybe the command you’re introducing has many other options, or maybe there are different ways to access a certain API. It doesn’t matter: right now, your learner does not need to know about those in order to make progress.

​
Good luck and have fun teaching others