Diátaxis Quadrants
Diátaxis quadrants
Every doc page is exactly one of four kinds. Mode-mixing is a review-blocker, not a stylistic preference.
The framework comes from diataxis.fr. The four quadrants:
| Quadrant | Purpose | Smell test |
|---|---|---|
| Tutorial | Learning by doing | "By the end, you've sent your first email." |
| How-to | Goal-oriented | "How do I X?" Always at least one runnable block. |
| Reference | Neutral facts | Tables, schemas, exhaustive flag lists. Light prose. |
| Explanation | Context, why | Prose-heavy. Diagrams. Decisions. No "Quickstart." |
Why mode-mixing is the failure pattern
A page that detours from how-to into architecture loses the reader who came for the how-to and confuses the reader who came for the architecture. The two audiences want different shapes. Tutorial readers want a sequence. How-to readers want a verb and a recipe. Reference readers want completeness and discoverability. Explanation readers want narrative and reasoning.
A quickstart that suddenly explains the daemon's event loop is a tutorial that broke. A reference page that opens with "Why we chose Tantivy" is reference that broke. A how-to that drifts into architectural rationale is a how-to that broke.
Cross-linking rules
- A how-to is allowed to point at an explanation.
- An explanation is allowed to point at a how-to.
- Neither is allowed to be the other.
If a how-to keeps wanting to explain why, the explanation belongs in a separate page that the how-to links to. Same for the reverse.
The pre-commit question
Before writing a heading, ask: which quadrant is this page in? If the answer is "kind of two of them," split the page. The split is almost always cheaper than the long-term cost of a confused page nobody can revise without arguing about what it's for.
See also
- How I Write Software Docs — the full synthesis
- A Recipe Solves a Goal — recipes live in the how-to quadrant
- Operationally Useful Docs — applies hardest to how-to; explanation is exempt from the deletion test