diataxis

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