joshuadavidthomas Diátaxis Documentation Framework
Apply the Diátaxis systematic framework to structure and write documentation.
The Four Documentation Types
Diátaxis identifies exactly four types, defined by two axes:
| Acquisition (study) | Application (work) | |
|---|---|---|
| Action (doing) | Tutorial | How-to guide |
| Cognition (thinking) | Explanation | Reference |
1. Tutorials — learning-oriented
Write tutorials as lessons. Take the learner by the hand through a practical experience where they acquire skills by doing.
- Use first-person plural ("We will...")
- Show where they're going up front
- Deliver visible results early and often
- Ruthlessly minimize explanation — link to it instead
- Focus on the concrete, ignore options and alternatives
- Aspire to perfect reliability
Load references/tutorials.md for full guidance.
2. How-to guides — goal-oriented
Write how-to guides as practical directions for an already-competent user to achieve a specific real-world goal.
- Name clearly: "How to [achieve X]"
- Use conditional imperatives ("If you want x, do y")
- Assume competence — don't teach
- Omit the unnecessary; practical usability > completeness
- Allow flexibility with alternatives
Load references/how-to-guides.md for full guidance.
3. Reference — information-oriented
Write reference as technical description of the machinery. Keep it austere, authoritative, consulted not read.
- Describe and only describe — neutral tone
- Adopt standard, consistent patterns
- Mirror the structure of the product
- Provide examples to illustrate, not explain
Load references/reference.md for full guidance.
4. Explanation — understanding-oriented
Write explanation as discursive treatment that deepens understanding. Answer "Can you tell me about...?"
- Make connections to related topics
- Provide context: why things are so
- Talk about the subject (title: "About X")
- Admit opinion and perspective
- Keep closely bounded — don't absorb other types
Load references/explanation.md for full guidance.
The Compass — When In Doubt
Ask two questions to classify content:
- Action or cognition? Is this about doing, or thinking?
- Acquisition or application? Is this for learning, or for working?
The intersection tells you which type you're writing. Load references/compass.md for detailed decision guidance.
How To Apply
- Classify the content — use the compass questions above.
- Check for type mixing — does this piece try to do two things at once?
- Separate mixed content — pull explanation out of tutorials, pull instructions out of reference.
- Apply the type's principles — follow the bullet points for that type above.
- Link between types — don't embed, cross-reference instead.
Do NOT create empty four-section structures and try to fill them. Let structure emerge from content.
Example
User asks: "Write a getting-started guide for our CLI tool."
- Classify: "Getting started" = the user is learning, by doing → Tutorial.
- Check: Not a how-to guide — the user isn't solving a specific problem, they're acquiring familiarity.
- Apply tutorial principles:
- Open with what they'll build: "In this tutorial, we will install the CLI and deploy a sample app."
- Lead through concrete steps with visible results at each stage.
- Minimize explanation: "We use
--verbosefor more output" not a paragraph on logging levels. - Link to reference for flag details, link to explanation for architecture.
- Result: A focused lesson, not a feature tour disguised as a tutorial.
Common Mistakes
| 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 |
Critical Rules
- Never mix types. Each type has its own purpose, tone, and form.
- The user's mode matters. Study vs. work is the fundamental distinction. Tutorials and explanation serve study. How-to guides and reference serve work.
- Link between types rather than embedding one inside another.
Deep Dives
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 |