Diátaxis Framework
also called Diátaxis, Four-Mode Documentation
A placement rule for technical documentation that separates four reader needs - tutorial, how-to, reference and explanation - so one page serves one need instead of mixing all four and serving none.
A platform team's documentation is comprehensive and its users keep asking questions it answers. The pages are accurate, so accuracy is not the problem. The problem is that one page starts as a tutorial, turns into reference halfway down and ends with an architectural explanation — and a reader arrives in exactly one of those modes.
Diátaxis names four modes and insists each page commit to one. Tutorials teach through doing, for someone who cannot yet do it. How-to guides get a competent reader to a real goal. Reference describes the machinery factually and does not teach. Explanation answers why. The four-mode model is Daniele Procida's; it circulated for years before acquiring the name Diátaxis in 2021, from the Ancient Greek for "across arrangement".
Why it matters
The mode mismatch is the mechanism behind the symptom. A reader working — mid-task, impatient — needs a how-to and abandons a page that opens with design rationale. A reader studying needs the rationale and gets nothing from a parameter table. A mixed page fails both, and it fails invisibly: the content exists, so nobody files a documentation bug.
The larger benefit is editorial. Diátaxis gives contributors a placement rule, which is what makes a documentation site survivable by many hands. Without one, every new page lands wherever its author was looking and the structure degrades at the rate of contribution.
Implementation patterns
- One mode per page, declared, so a reader leaves immediately when it is the wrong one.
- Mode in the information architecture, not only in the writing: separate top-level sections and distinct URL prefixes, so the navigation itself asks the reader which need they have.
- A write test: name the mode and the reader's need before writing. A page answering neither becomes a mixed one.
- Migrate by traffic, not by tree. On a large wiki a small minority of pages carries most reads — 40 of 1000 pages serving over half of all views is a common shape — so convert those first.
- One review rule: a change adding a how-to does not add explanation to it. Link instead.
- Auto-generate reference and hand-write the other three, since reference is where drift is both most likely and most mechanically fixable.
Industry example
The framework spread beyond its origin project for exactly that editorial reason: a major Linux distribution vendor rebuilt its documentation practice around the four modes, and a large edge-networking vendor used Diátaxis as the information architecture for its developer documentation, treating it as the arbiter when a new page's placement was unclear. The reported benefit in both cases is contribution scaling rather than reader satisfaction: with a placement rule, engineers add pages without an information architect in the loop.
Failure scenarios
- Explanation as a dumping ground for everything that fits nowhere, recreating the original mixture under a new heading.
- Generated reference with no explanation anywhere: a complete API surface and no mental model, the classic "documented and unusable" API.
- Tutorials that assume competence, the most common single defect, because the author cannot unsee what they know and the tutorial becomes a how-to beginners cannot follow.
- Inventing a fifth bucket, usually "concepts", which quietly re-mixes explanation and reference.
Trade-offs
| Choose | Gains | Pays |
|---|---|---|
| Four separated modes | each reader served · a placement rule contributors follow | one topic across three pages that must stay consistent |
| One page per topic | nothing to cross-reference · feels complete | serves no reader fully · grows until it serves none |
| Modes without IA separation | cheap to adopt | a reader cannot tell a page's mode until they read it |
When not to use it
Below roughly 30 pages the structure costs more than it returns and a good index beats a taxonomy. For internal operational documentation — runbooks, on-call guides — the shape differs: those are how-to under time pressure, and four modes put what a responder needs at 03:00 behind a navigation decision. And for a single-audience reference, such as an internal API used by two teams who know the domain, the reference mode alone is the honest answer.
Interview question
Q: A developer platform's documentation is comprehensive and its users still file tickets the docs answer. Diagnose it and say what you would change first.
What a strong answer covers: diagnose mode mixing rather than missing content, verified by reading the three most-visited pages and asking which single reader need each serves. Change the top pages first, chosen by analytics rather than tree position, splitting each into the how-to a working reader needs and the explanation a studying reader needs, with reference generated. Put the placement rule in the contribution guide, because the fix has to survive the next hundred pull requests. Name what you will not do: a full reorganisation of the long tail, which costs months and moves almost no traffic.
Quick check
Quiz: Why does a comprehensive documentation set still fail its readers? — Because pages mix tutorial, how-to, reference and explanation while a reader arrives in one mode only, so a mixed page serves none.
Flashcard: What are the four Diátaxis modes and who does each serve? — Tutorial for someone learning by doing; how-to for a competent reader with a goal; reference for lookup; explanation for understanding.