Diátaxis, a new foundation for Canonical documentation

Our on-going documentation transformation project aims to make our documentation the best it can possibly be – an exemplar of excellence for the industry. We’re working on four distinct pillars of documentation to achieve this. The first of these pillars is direction. It defines what is quality in documentation, and answers the question: what makes documentation good?

The principle that guides us in this is simple: good documentation serves the needs of its users. We are adopting the Diátaxis documentation framework to help us put this principle into practice.

Our direction

The Diátaxis framework is a light-weight and pragmatic approach to meeting users’ needs in a systematic way, by prescribing a core structure for technical documentation. It provides standards, and a methodology to guide us – it’s a map and a compass.

Direction is a good metaphor for our work in documentation. When you’re going somewhere, you need to have a clear idea of where you’re headed, even if you don’t necessarily know precisely what the final destination is. If you’re charting new territory, there might not even be a final destination. When you can’t plan the whole journey in advance you need to be prepared to adjust for changing circumstances and what you find along the way.

Still, your intended direction should be clear. At any given moment you need to be able to know which way you’re actually facing, and where you are. You need to know what’s between you and your next point along the way, and you need to know what to do to get there.

Our direction is quality. The Diátaxis framework will be our map and compass, our standards and our guide, towards quality in documentation.

Four types of documentation

Diátaxis identifies four distinct modes or types of documentation: tutorials, how-to guides, reference and explanation. Each corresponds to a different need a user has at different times in their cycle of interaction with a technical product. Each has its own purpose, each requires its own distinct form and style – and each should be kept distinct from the others.

Tutorials

A tutorial is a lesson, safely in the hands of an instructor.

Sometimes the user is learning to use the product, or some aspect of it. They are becoming familiar with it, learning what it’s like to use it and what can be done with it. Then they need to be guided along a carefully-constructed learning path by a teacher, who talks them through it step-by-step. At the end of it, the learner will have completed a small but meaningful exercise, with something concrete to show for their efforts, and with some new understanding, knowledge and confidence that they didn’t have before. This is what a tutorial does.

A tutorial should look and feel like a lesson. It’s obliged to provide a successful learning experience. It is not a learning experience to have things explained to you, or facts presented to you. The only way to learn a skill is by doing, so a tutorial neither contains explanation nor presents facts: it contains only directions for things to do, through which the reader will learn.

How-to guides 

A how-to guide is a recipe, that shows the reader how to achieve something. 

When the user is getting something done they are at work, applying their knowledge to a real task or problem. Now they need to be shown the key steps to take. What they need is a how-to guide.

Unlike a tutorial, a how-to guide is not responsible for providing a learning experience. It has no obligation to teach. It can assume that the reader has already acquired competence and familiarity with the machinery, its operation, the language used to talk about it and so on. Its obligation is to show a user how to get something done, step-by-step. It’s the obligation of the user to know what they want to get done, and to be able to apply the guide to the needs of their particular situation.

Reference

Reference material is description, providing facts about the machinery the user operates.

How-to guides and tutorials are both concerned with practical steps. On the other hand, sometimes the user doesn’t need to know what to do, but what is the case. The user at work needs to look up information about the machinery they’re working with. They want up-to-date and reliable facts (specifications, descriptions, implementation details) – they’ll find them in reference material.

Reference is independent of what anyone needs to do. It’s not a place for explaining, or instructing. Its obligation is to present the dry facts about the machinery as completely and reliably as possible, so that the user can work with it effectively. The structure or architecture of reference documentation should follow that of the machinery, so that one can be mapped to the other.

Explanation

Explanation is discussion, to illuminate a topic.

At a certain time, a user might look for deeper or better understanding of the product and how it functions. They want to see it in context, from different perspectives; they want questions answered about why things are the way they are. Explanation exists to answer those needs.

Explanation’s obligation is to help the user move from mere acquaintance or working familiarity with something to a deeper, broader understanding of it. It’s free to bring in anything that helps achieve this: examples, comparisons, different perspectives, histories, choices and more. Explanation should be like your knowledgeable friend, sharing their insights with you.

A place for everything and everything in its place

The relationship between these four modes of documentation is what gives Diátaxis its distinctive structure.

For any given piece of documentation, it should be clear what kind of documentation it is – it will always be one, and only one, of the four types. This shows what that documentation should include. And equally importantly, it shows what does not belong in a particular piece of documentation, and should instead be placed elsewhere.

This serves authors as well as users. It helps authors put things in the right place in documentation, and it helps users find them.

An example

Let’s say you’re writing some security documentation for a product. You want to make sure that all the important things you know about security will be included in the documentation. Under Diátaxis, instead of thinking about a general, undifferentiated Security topic, you will know that anything you write about security will fall into one of the four documentation types. 

So, if you start by writing security reference documentation, you will know that you should be producing clear and simple statements of fact. Explanation of a security feature or function, or showing how to use it – those don’t belong here. There is a place for them: a different place. If those things are required, then there should also be a security explanation topic, or a security how-to guide. This immediately makes life easier for the documentation author, who recognises that explaining and showing how-to are also important, and need to be included, but who might otherwise struggle to find a way of ordering and structuring all this content.

And for the user, who always has a particular need at any given moment, it’s clear where to go to have that need met. When a user needs to look up something, they know that they’ll find it in the reference material. And while they’re there, they won’t be distracted by explanations that they weren’t looking for, or instructions how to do something.

On the other hand, when they do want to know how to do something, they’ll find what they need in a how-to guide, that similarly avoids obliging the reader to pick their way through reference or explanation in order to find out what they actually need to do.   

Diátaxis in our documentation work

The Diátaxis structure serves as a map and a compass in documentation, a toolset to keep it going in the right direction. At any moment, it provides questions to ask of what we are and should be writing, and guidance about how we should do it:

• Does our user need to be guided in action, or do they need knowledge?
• Is our user at study or at work?

Because the structure makes these clear distinctions, it becomes easy to see when one component of documentation has become confused and muddled with forms that belong to another. Reference material that breaks off from describing the machinery in order to show how to do something, or a tutorial that interrupts its own lesson to digress into explanation are typical examples of confused, confusing documentation. Diátaxis shows how they’re going wrong, and why they’re going wrong, in a way that’s straightforward to assimilate.

As a lens, Diátaxis is unforgiving. The more thoroughly the structure is adopted, the more mercilessly it exposes gaps, missteps and conflations.

Naturally this means that the first thing Diátaxis does is make existing documentation look worse, not better: problems are harder to hide and ignore, things in the wrong place stand out inescapably. But this is how it should be, because no problem can be addressed without being able to see it clearly first.

At Canonical 

We’re implementing this framework in our technical documentation, restructuring existing material and using it to guide the creation of new content. The work is taking place right across our documentation properties – you can see it already in several of them, including Anbox Cloud, Charmed Kubeflow, the Juju Operator Lifecycle Manager, the OpenStack Charms guide, Ubuntu Core.

In each case, you will see a high-level division of the technical documentation into the four types, clearly signposted so that it’s obvious what kind of material you will find, and where.

As noted above, Diátaxis has a side-effect of spotlighting problems in documentation, and we can already see them more starkly where Diátaxis has been applied. Having that exposed in public only helps accelerate the process of improvement.

The end result of our project will be documentation across our products and services that shares common structures, structures that in themselves are easier to navigate to find what you need in them.

What this means for you

This is about you, as a person who turns to our documentation when using our software, because you need something. It means our documentation will come to be structured around your needs and written to meet them.

In our documentation, you should be able to find what you expect where you expect it, in a form that meets your expectations. As a reader, you should not have to do extra work to discover or remember where the content you need has been placed. You should not be forced to change mental gears because what you’re reading has switched modes half-way through. You should not be distracted by irrelevant content. And you should never be made to waste time searching for what you need. If it’s not there, it should be obvious that it’s not there, because there’s only one place where it could be.

In a sentence, we’re going to put your needs first in our documentation, so that you enjoy more success with the software we create. It’s going to take time, but we’re committed to delivering on this promise.