Diátaxis#
Overview#
Diátaxis was developed over the years by Daniele Procida. It is a mental framework for organizing and managing documentation in a way that makes it easier to write, maintain, and navigate. This is just a summary of the system, and why it works well. If you are interested in learning more, I would recommend jumping over to the site and reading it in full.
Daniele started the formalization of the system while at Divio, so you might also see it referred to as Divio's The Documentation System.1 I pull some quotes and thoughts from there as well. While he does not directly reference it, he seems to have heavily borrowed from Jacob Kaplan-Moss's Writing Great Documentation: What to Write.2 They worked together at Django, so it is not surprising that Jacob's ideas would have influenced Daniele.
Why was this created?#
Let's start with this assumption:
It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it. Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to.3
I don't necessarily agree with this premise for all products.4 But I do think it should apply to a product with a large enough interface (like codebases), or a product not built with world-class UX designers. Since I don't intend to be a world-class UX designer, I always assume I need to write good documentation.
I have attempted writing documentation many times, and it has always been a struggle. So it makes me feel good that Daniele goes on to say:
Nearly everyone knows that they need good documentation, and most people try to create good documentation. And most people fail. Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way. This system is a way to make your documentation better, not by working harder at it, but by doing it the right way. The right way is the easier way - easier to write, and easier to maintain.3
This is the main reason how I stumbled upon this. It always seemed like a struggle, and I was looking for a better way. Using this framework has made it much easier and more enjoyable to write documentation.
How does it work?#
The system is based on the idea that there is not one type of documentation, but rather four. Each type of documentation is distinct: it must be written differently, and its used in different circumstances. They are all necessary, just at different stages of the user's journey.
The four types of documentation are Tutorials, How-to Guides, Reference, and Explanations. Each type of documentation has a singular purpose, and the different purposes are have clear boundaries. Here is a useful visual to help understand the system5:
| Tutorials | How-to guides | Reference | Explanation | |
|---|---|---|---|---|
| what they do | introduce, educate, lead | guide | state, describe, inform | explain, clarify, discuss |
| answers the question | Can you teach me to…? | How do I…? | What is… | Why…? |
| oriented to | learning | goals | information | understanding |
| purpose | to provide a learning experience | to help achieve a particular goal | to describe the machinery | to illuminate a topic |
| form | a lesson | a series of steps | dry description | discursive explanation |
| analogy | teaching a child how to cook | a recipe in a cookery book | information on the back of a food packet | an article on culinary social history |
Why four types?#
Without getting too deep into the weeds (check here for a deep dive), Diátaxis makes the argument that a skill will need to be both acquired and then later applied. Learning a skill requires both action (practical knowledge) and cognition (theoretical knowledge). Depending on how the user is attempting to uplevel their skill, they will need different types of documentation6:
| need | addressed in | the user | the documentation |
|---|---|---|---|
| learning | tutorials | acquires their craft | informs action |
| goals | how-to guides | applies their craft | informs action |
| information | reference | applies their craft | informs cognition |
| understanding | explanation | acquires their craft | informs cognition |
It can also be viewed as two separate axes:
This is how there ends up being four types of documentation. Its not that Daniele decided on three or four himself, and then built the system to fit his narrative. It is that he dove into what the user needs in order to learn a skill, and then built the system on top of that.
Why does it work?#
The system works by making the expectations clear to both the documentation author and the reader. Each type of documentation has a clear and singular purpose, so the author knows what they are writing and when they are done. The reader knows what to expect when they are combing through the documentation, and not have to sift through a bunch of irrelevant information to them.
When these clear boundaries between different documentation types are not set up, the documentation tends to turn into a melting pot. Diátaxis calls this blur,7 but I prefer The Documentation System's term the tendency to collapse.8 Since there is overlap between the different types of documentation, and the needs of the user, it is easy for the author to start to conflate the different types. Check out this visual on which roles are shared between the different types of documentation:
| Role | Type 1 | Type 2 |
|---|---|---|
| guide action | tutorials | how-to guides |
| serve the application of skill | reference | how-to guides |
| contain propositional knowledge | reference | explanation |
| serve the acquisition of skill | tutorials | explanation |
You can easily see how each type of documentation shares some of the same roles. While authors can make the best attempts to delineate between the dfferent types, without clear boundaries, the documentation is guaranteed to start to bleed into each other. Calling out the type of documentation you are writing, and the purpose of it, helps to keep the documentation clean and focused.
How I apply it#
I have started to apply this system at work, and it has really helped our team focus our writing. We have 4 separate tabs within our monorepo, each dedicated to one of the four types of documentation. And then within each tab, we organize by subject. This is an extremely rigid way to apply the system, but it has worked well for us.
On my personal website, I am trying a more fluid approach. Every piece I write is tagged with one of the four types, instead of organizing them into separate sections. You can see at the top of this page that I have tagged this as an explanation. This website is more for me to practice writing, show off myself, and help others, so I didn't feel the need to be as rigid. I am not sure how well either of these approaches will work in the long run, but I am happy with them both for now.
Criticisms#
I do not have any criticisms of my own, and it was hard to find criticisms online. The only major one I found was that the system does not describe how to introduce the documentation in the form of a README.9 There needs to be a strong landing page that orients the user when they first arrive, to help them on their journey. A good README should include all four types of documentation, in summary form, and then link to the fuller documentation.10 This is even something that the author of the system agrees with, but he just says that it should live outside of the system.11
Other Resources#
- Writing Great Documentation: What to Write by Jacob Kaplan-Moss - The original inspiration for Diátaxis
- What nobody tells you about documentation (video) - Daniele Procida's talk on the system
- Documentation as a way to build Community - A blog post on why organized documentation is important
- Django Documentation - A great example of docs that follow the Diátaxis system
- Pytest Documentation - A great example of docs that follow the Diátaxis system