Skip to content

The Grand Unified Theory of Documentation (Diátaxis)⚓︎

Summary⚓︎

When it comes to writing technical documentation, there is a right and a wrong way to do it. A particularly well authored framework is the Diátaxis 1 framework. The Diátaxis framework is summarized as follows...

The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.

Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.

In Diátaxis, each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.

documentation-split.png

Technical documentation should be structured explicitly around these four types, and should keep them all separate and distinct from each other.

In other words, what we call documentation is fundamentally not one thing, but four. Understanding the implications of this, and how those four different things work, can help improve most documentation.

Considering documentation in such a way will inevitably produce a better end result. This section will explain in detail how to write quality documentation.

Warning

Because this is an established framework, the respective sections will be taken verbatim from the official documentation.

Rules to Follow⚓︎

  1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why.

  2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it).

  3. Think in terms of a blog post/tutorial, not technical API docs as a starting point. This helps with adoption because people want to understand the thing first and then dig into API (just because you may not doesn't mean that others are the same).

  4. Don't be lazy. Show respect for the people taking the time to use your stuff and put in the effort (grammar, structure, quality of examples, etc).

References⚓︎

  1. The name Diátaxis comes from the Ancient Greek δῐᾰ́τᾰξῐς: dia (“across”) and taxis (“arrangement”). ↩