Exploring Diataxis - on structuring documentation

I recently spent some time exploring Diataxis, a documentation framework that promises to make technical documentation not just readable but genuinely useful. You might have heard of Diataxis or you might have struggled to structure your project documentation between different types of documents. Or you are genuinely curious. This blog is for you.

Illustration copyright Linette Voller 2021, from the Diataxis website.

What is Diataxis?

Diataxis categorizes documentation into four distinct types of documents, each serving a unique purpose:

Tutorials: These are all about the acquisition of skills through action. They don’t explain ; they immerse users in a learning experience, encouraging experimentation and practice. Tutorials are for those starting from scratch, guiding them through a process without overwhelming them with theory.

How-to Guides: Assuming you are already proficient, these guides focus on the actions you need to do, they are about applying skills. They are task-oriented, designed for users who know what they want to achieve but need guidance on how. They don’t delve into explanations or references ; they are strictly about doing. The list of how-to guides is a good list of what your product can do.

Reference: This category is information-oriented, describing the product in a way that’s meant to be consulted, not read cover to cover. It’s austere and systematic, perfect for API docs, classes, functions, or even lists of extensions. Here, it’s all about describing without opinion, often mirroring the structure of the product itself. Examples can be included to help clarity.

Explanation: Focused on the acquisition of skills via cognition, explanations provide a discursive form of understanding. They give users a high-level view, background, and context. They are ideal for architecture documents or answering why questions. Here, opinions can be shared as long as they are explicitly labeled as such. Make sure to connect pieces of documentations in these documents.

My View on Diataxis

I came in, reading about Diataxis as skeptical. But I found it most useful for deciding what to exclude from a given documentation type. It’s a lens through which to view content organization, ensuring each piece of documentation serves its intended purpose without clutter and with less duplication I think thanks to a sens of focus.

Reference Docs: I’m generally not a fan of these, particularly for software where tools like JavaDocs outputs are already integrated into IDEs (the joke is that you put the JavaDocs as appendix of a book to make it look bigger).

Explanations: These are my favorites. They provide overview, context, opinions. From them, a user can hang and organise knowledge provided in how-to guides for example. An architecture document lives in this category.

Tutorials: Tutorials at not here to lecture but only as a way to experience the technology and learn from this experience: a visceral learning of sort. This is quite liberating to feel you don’t need to provide context and explanations in such documents.

How-to guides: They assume an average state of the art knowledge of your technology, this is equally liberating for the writer to not have to stop the flow of a guide for contextual information. Instead, the guide stays focused on how to address a concrete problem. Assuming average knowledge really helps decide what makes it and what does not.

Last but not least, I think quite a few knowledge might not neatly fit into these four categories, so stay flexible and that’s what the Diataxis folks seem to encourage.

Funny enough, the Diataxis documentation does not follow the Diataxis approach.

Other References

While researching this topic, I also found the Good Docs Project which gives templates for quite a few styles of documentation.

To use it or not to use it, that is the question

In conclusion, while Diataxis isn’t a one-size-fits-all solution, it’s a powerful framework for those looking to enhance the clarity, usefulness, and user-friendliness of their documentation. I would recommend to soft apply it to help make decisions on your documentation but not go religious about it at the risk of bringing back friction (in your team and in the readers). And the last thing you need when writing or reading doc is friction.