Tutorial

General guidelines

Tutorials should be designed to make a difficult task easier by offering simple instructions for processes and steps that are potentially complicated. A tutorial should allow users to save time and energy that they would otherwise have to spend researching. Their usefulness can be measured using a time vs. knowledge ratio: the time investment should not exceed the amount of knowledge offered; for instance, a 30-minute tutorial on how to carry out a very simple task is not a good idea, there are probably ways to make it shorter and more to the point. ^[2]

Characteristics of a good tutorial

Four main aspects should be carefully considered in order to create a good tutorial: these are language, organization, presentation and content.

Language

Unless your tutorial is intended for advanced users, it is better to avoid any technical terms and specialized jargon and to opt for the ‘layman’s language’: it must be remembered that if users are relying on your tutorial it means that they are no experts on the subject matter. However, the rule of thumb is always: know your audience.

Organization

The planning phase is important: create an outline or list of what your tutorial will contain and what its structure will be; this will help keep it clear and organized.

Go through the process using the eyes of a first-timer: take notes of each step of the process, as this will help you not to skip any passages. Think of the questions and troubles you had when you went through the process for the first time. Include also the minor steps that might seem obvious to you as an expert: they are not for someone who is a beginner.

Presentation

Make sure you use a proper formatting. Test all the downloads you included, if any, and make sure all links are live.

Your presentation should be accessible to the majority of users: take into account that not everyone can download large files or visualize Quicktime or Flash. A good solution could be posting different versions of your tutorial in different formats and let people choose what option suits them.

Content

Start by giving users an introduction: this should include a brief explanation of the tutorial’s goals, a list of what is needed to complete the project, and an overview of the areas you will cover. Remember to specify what the skill level of the tutorial is (e.g. beginners, intermediate or advanced).

Take into account the time factor: aim for brevity but include all the important details.

Remember that cohesion is an essential part: if the tutorial is part of a series, plan the order carefully so that each tutorial builds on what was explained in the previous ones.

Step by step

• Create the outline of the tutorial and decide what its structure will be.
• Go through each step of the process as if you were doing it for the first time.
• Write down each passage and the problems you encountered.
• Whether you are creating a step-by-step video or writing a how-to article, start by giving an introduction (e.g. topics explained, areas covered, requirements, level of difficulty).
• Describe each step thoroughly and include also minor steps.
• Provide instructions in a clear, detailed, professional and comprehensible way (no technical jargon).
• Credit your sources.
• Capture screenshots or make screen videos.
• Test all your links and downloads; verify that the format you are using is easily accessible.
• Make sure the process is organized into logical steps.
• Ask a friend to try your tutorial and test it yourself.