Structure, classify, and write documentation using the Diátaxis framework. Use when writing docs, README files, guides, tutorials, how-to guides, API references, or organizing documentation architecture. Also use when asked to improve documentation, restructure docs, decide what type of doc to write, or classify existing content. Covers tutorials, how-to guides, reference, and explanation.
Apply the Diátaxis systematic framework to structure and write documentation.
Diátaxis identifies exactly four types, defined by two axes:
| Acquisition (study) | Application (work) | |
|---|---|---|
| Action (doing) | Tutorial | How-to guide |
| Cognition (thinking) | Explanation | Reference |
Write tutorials as lessons. Take the learner by the hand through a practical experience where they acquire skills by doing.
Load references/tutorials.md for full guidance.
Write how-to guides as practical directions for an already-competent user to achieve a specific real-world goal.
Load references/how-to-guides.md for full guidance.
Write reference as technical description of the machinery. Keep it austere, authoritative, consulted not read.
Load references/reference.md for full guidance.
Write explanation as discursive treatment that deepens understanding. Answer "Can you tell me about...?"
Load references/explanation.md for full guidance.
Ask two questions to classify content:
The intersection tells you which type you're writing. Load references/compass.md for detailed decision guidance.
Do NOT create empty four-section structures and try to fill them. Let structure emerge from content.
User asks: "Write a getting-started guide for our CLI tool."
--verbose for more output" not a paragraph on logging levels.| Mistake | Why it fails | Fix |
|---|---|---|
| Tutorial that explains everything | Explanation breaks the learning flow — learner loses focus | Move explanation to a separate doc, link to it |
| How-to guide that teaches basics | Competent users don't need onboarding — it wastes their time | Assume competence, or split into tutorial + how-to |
| Reference with opinions and advice | Users consulting reference need facts, not guidance | Move advice to explanation |
| Explanation mixed into reference | Dilutes both — reference becomes verbose, explanation can't develop | Separate into distinct documents |
| "Getting started" that's actually a feature tour | No learning goal, no coherent journey — user doesn't acquire skill | Pick one thing the user will accomplish, build toward it |
| Creating empty Tutorials/How-to/Reference/Explanation sections | Structure without content is useless scaffolding | Write content first, let structure emerge |
Load reference files on demand for detailed guidance:
| Topic | File |
|---|---|
| Writing tutorials | references/tutorials.md |
| Writing how-to guides | references/how-to-guides.md |
| Writing reference docs | references/reference.md |
| Writing explanation | references/explanation.md |
| The compass decision tool | references/compass.md |
| Tutorials vs how-to distinction | references/tutorials-how-to.md |
| Reference vs explanation distinction | references/reference-explanation.md |
| Workflow methodology | references/how-to-use-diataxis.md |
| Why Diátaxis works (foundations) | references/foundations.md |
| The two-dimensional map | references/map.md |
| Quality in documentation | references/quality.md |
| Complex hierarchies | references/complex-hierarchies.md |