The idea of a tutorial

Sooner or later, almost everyone who looks at some software that they or their team have created imagines a user getting to grips with it, and a pang of empathy for that unknown person prompts them to think: what we need here is a tutorial.

And they are always absolutely right.

In the Diátaxis documentation framework, tutorials are one of four equal types of documentation, amongst how-to guides, reference and explanation. 

However, tutorials are first amongst these equals, in two ways. For readers of documentation, they are a starting-point, the first encounter on a user’s journey. For authors, the way a tutorial is constructed and its content do more to shape the rest of the documentation than any of its other parts.

In addition, tutorials are by some margin the most difficult part of documentation to conceive, create, keep up-to-date, and test for quality. 

All in all, this makes the tutorial an especially significant part of documentation to deal with.

Tutorials versus how-to guides

Tutorials are and need to be distinguished from how-to guides, but are very frequently confused with them.  (In fact, at the time of writing, Canonical publishes a large number of “tutorials”, that are in fact how-to guides – we’re in the process of addressing this confusion.) This is quite understandable. Tutorials and how-to guides are both practical guides, that show the user how to do something, step-by-step. 

The clue to the nature of a tutorial is in the name: it’s something that’s delivered by a tutor, a teacher who looks after the interests of a pupil. A tutorial delivers what the pupil needs to learn, in order to acquire basic competence, whereas a how-to guide is what the user asks for to help perform a particular task.

A tutorial is a learning experience. People learn skills through practical, hands-on experience. What matters in a tutorial is what the learner does, and what they experience while doing it.

On the other hand, a how-to guide serves the user who already knows what needs to be done, and wants to be guided through it. Competent professionals typically refer to how-to guides regularly. A pilot will follow the same check-lists several times a day. A mechanic will check the process in the maintenance manual. A chef will consult a recipe (even a recipe that they wrote themselves).

The difference is not that how-to guides are more “advanced” than tutorials. The difference is that tutorials are for someone who is learning a skill, however advanced or complex, and how-to guides are for someone who is applying a skill to their work.

One true path

We’re completely overhauling our approach to documentation at Canonical. Part of this project is to ensure that each product has the tutorial it needs, that will provide the way in for new users, and will accompany them to a level of basic competence.

Our model for product tutorials is one true path.

One

That is to say: each product should have a tutorial – just one. 

The tutorial might be in several parts, and typically will need to be. It might even need to exist in more than one variant. But, it should be clearly a single tutorial, the tutorial for the product. 

This is important both for users and for documentation maintainers. A user should not have to expend additional effort working out where to look and what to read in order to become familiar with a product. Everything should be in one place (and that place is with the rest of the product’s documentation).

For the documentation maintainer, it should be equally clear what needs to be maintained and kept up-to-date; not a scattering of multiple articles that overlap and leave gaps, but a single, coherent, thought-through resource.

There is no question that a tutorial that is treated as the go-to resource for new users will have great deal of pressure on it. Every weakness in it will be highlighted and exposed. But, this is part of the process of the creation and maintenance of good tutorials: they need that pressure.

If the documentation authors are able to respond to it, eventually the tutorial will become a resource that the whole community of users can refer newcomers to, with confidence. By focusing pressure in one place, a great deal of distraction is removed from many others.

True

The tutorial must be true. It needs to be accurate and precise. It needs to be true in other senses too: it must always point the user in the right direction, like a compass; it must run straight and smoothly, like a wheel. And like a true path, it must steer the user away from mishap and lead to success.

This is only possible for a tutorial that is rigorously conceived, implemented and tested. 

There are some aspects of a tutorial whose truth can be ascertained in advance, like where it needs to get to, and what kind of success it offers the user. There are many more though that will only be discovered in practice, that require us to use trial and error until we work out what actually works best.

A tutorial must stay true. The software that it refers to, and its context, will be in a continuous state of change. The tutorial needs to change with them.

Finally, a tutorial must represent the whole truth – it must be a complete learning experience, that takes the learner all the way to the promised destination, and visits all the points it needs to along the way.

Path

This is why a tutorial should be thought of as a path. It’s a journey that the new user will take, through unfamiliar territory. A good path is the shortest, safest route, that manages to cover all the required ground, and offers the traveller sight of the wider terrain too, even if they don’t venture into it.

It should be possible for every user to follow it, and for each user to follow it again and again, always experiencing the same journey. It must be reliable, for all the different learners who put their faith in it.

The journey the path describes needs to be a meaningful one, that tells a story. The user is the protagonist in this story, and the tutorial leads them along the path, to success (literally, the tutorial educates the user – education comes from the Latin verb to lead).

Opinionated, supported, guaranteed

Software producers shouldn’t be surprised at the way their products are used – if you provide flexible tools to creative and ambitious users, you never know what someone will do with them.

To get to that stage of competence and confidence, users need to be supported along a learning path, and this path is not for the user to work out, but the author. It’s not merely permissible to be opinionated in a tutorial, it’s obligatory – the path and the vision of the software that it provides need to be determined by the creator’s understanding of it, and need to set the user’s expectations accordingly. 

The tutorial lays down a supported baseline of usage and practice. The user will go beyond this, into territory that they make their own, but they will do this later, on their own terms. Even then, the tutorial will provide a safe, known place of return, and serve as a reminder of usage and practice that are guaranteed to work. 

Documentation is a contract with the user; the guarantee is part of that contract.

Beyond product documentation

The principle at the core of this vision of a tutorial is education. It makes sense for a product that wants to acquire new users, but the ideas outlined above work for any documentation intended to educate. 

An excellent example of documentation-as-education is outlined in an article by Gary Niemen at Spotify (it’s a thoughtful and insightful piece and highly recommended). It’s not about product documentation, but about the on-boarding process for engineers; it discusses how tutorials are used at Spotify to serve new engineers, who need to learn the right way to use the platform tools available to them.

 Each engineering discipline at Spotify is represented by what they call a “Golden Path” tutorial. As with our conception of product tutorials, it relies on the metaphor of a path, and asserts that there should be one and only such path for each case.

A new engineer who is to become a competent, confident team-member, familiar with processes, tools, workflows, nomenclature and so on will get there by following the Golden Path for the appropriate discipline. 

Having first been adopted several years ago, this approach has proved its long-term value; most notably, it has removed doubt and stumbling-blocks from the on-boarding experience of engineers, and reduced the burden of supporting them. It has reduced fragmentation of tools, processes and knowledge. It continues to solve the many problems that an autonomous, agile working culture can throw up.

What to expect at Canonical

As the Spotify article acknowledges, the creation and maintenance of tutorials of this kind is a substantial investment and commitment.

In fact, creating and maintaining a tutorial is more than just a substantial investment: it has to be recognised as the commitment to carry a genuine burden, for as long as the tutorial continues to exist (this is another reason why there should be only one tutorial per product – so that it can be properly maintained).

We’re making this commitment, and are preparing to shoulder the burden. As we work through our numerous documentation properties, they’ll each be furnished with a tutorial on the “one true path” model, an opinionated, supported and guaranteed way to get to grips with the product. It’s going to be a long-term project, that proceeds incrementally.

We hope the benefits for users will be obvious. We want to see fewer, but much better, entry-points into our products. We want to provide guarantees that a Canonical tutorial will lead to user success. We want new adopters of our products become more productive and feel more at home, faster.

We have every confidence that these results will make the burden worth carrying.