joshuadavidthomas/agent-skills/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:

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.

1. Result: A focused lesson, not a feature tour disguised as a tutorial.

Common Mistakes

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: