--- title: Diátaxis, a new foundation for Canonical documentation description: Good documentation serves the needs of its users. The Diátaxis documentation framework will help us put this principle into practice. url: https://canonical.com/blog/diataxis-a-new-foundation-for-canonical-documentation?format=md --- 1. [Blog](https://canonical.com/blog) 2. Article --- [Daniele Procida](https://canonical.com/blog/author/danieleprocida "More about Daniele Procida") 15 December 2021 # Diátaxis, a new foundation for Canonical documentation [documentation](https://canonical.com/blog/tag/documentation) --- Share the article 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](https://ubuntu.com/blog/the-future-of-documentation-at-canonical) 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**](https://diataxis.fr/) 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](https://anbox-cloud.io/docs), [Charmed Kubeflow](https://charmed-kubeflow.io/docs), the [Juju Operator Lifecycle Manager](https://juju.is/docs/olm), the [OpenStack Charms](https://docs.openstack.org/charm-guide/latest/) guide, [Ubuntu Core](https://ubuntu.com/core/docs). 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. [Get in touch Interested in running Ubuntu in your organization?](https://ubuntu.com/about/contact-us/form) ## Sign up for our newsletter Get the latest Canonical news and updates in your inbox. Work email: \*I agree to receive information about Canonical's products and services. By submitting this form, I confirm that I have read and agree to [Canonical's Privacy Policy](https://canonical.com/legal/dataprivacy). Sign up ## Share on --- ## Related posts [### A year of documentation-driven development](https://canonical.com/blog/a-year-of-documentation-driven-development) For many software teams, documentation is written after features are built and design decisions have already been made. When that happens, questions about how a feature is... [Yanisa Haley Scherber](https://canonical.com/blog/author/yanisa-hs) 17 February 2026 [### Documentation, development and design for technical authors](https://canonical.com/blog/documentation-development-and-design-for-technical-authors) Typically, a technical writer takes the product created by a development team, and writes the documentation that expresses the product to its users. At Canonical we take a... [Daniele Procida](https://canonical.com/blog/author/danieleprocida) 3 December 2024 [### Introducing Canonical’s Open Documentation Academy](https://canonical.com/blog/introducing-canonicals-open-documentation-academy) tldr; Our Open Documentation Academy starts this week with our first weekly Documentation Office Hours on Friday 1st March 2024 at 16:00 UTC. Everyone is welcome! Keep reading,... [Graham Morrison](https://canonical.com/blog/author/morrisong) 26 February 2024 [### Help us build better doc](https://canonical.com/blog/help-us-build-better-doc) We want you to join our Ubuntu circle, and help us document MAAS. More minds, more eyes, more hands make better doc. [Bill Wear](https://canonical.com/blog/author/billwear) 17 March 2023