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:

1. Action or cognition? Is this about doing, or thinking?
2. 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

1. Classify the content — use the compass questions above.
2. Check for type mixing — does this piece try to do two things at once?
3. Separate mixed content — pull explanation out of tutorials, pull instructions out of reference.
4. Apply the type's principles — follow the bullet points for that type above.
5. 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."

1. Classify: "Getting started" = the user is learning, by doing → Tutorial.
2. Check: Not a how-to guide — the user isn't solving a specific problem, they're acquiring familiarity.
3. 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 --verbose for more output" not a paragraph on logging levels.
   • Link to reference for flag details, link to explanation for architecture.
4. 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