Writing Documentation With Diataxis

The Diataxis Compass — Your Primary Tool

When uncertain which type you need, answer two questions:

1. Does this inform ACTION or COGNITION?

   • Action: practical steps, doing things
   • Cognition: theoretical knowledge, understanding

2. Does it serve ACQUISITION or APPLICATION?

   • Acquisition: learning, study
   • Application: working, getting things done

Then apply the matrix above.

Core Principles by Type

Tutorials (Learning by Doing)

• You're responsible for the learner's success
• Focus on doing, not explaining
• One path only — no alternatives
• Perfectly repeatable
• Build the "feeling of doing"

How-to Guides (Working to Achieve Goals)

• Address real-world problems, not tool features
• Assume competence
• Provide logical sequence with conditionals ("If X, do Y")
• Seek flow — anticipate the next move
• Focus on tasks, not tools

Reference (Facts While Working)

• Describe, don't instruct
• Neutral, factual tone
• Completeness matters
• Use standard, consistent patterns
• Provide succinct examples

Explanation (Learning to Understand)

• Talk about the subject from multiple angles
• Answer "why" — design decisions, history, constraints
• Make connections to related concepts
• Permit opinion and perspective
• Take the higher, wider view

Workflow: Creating Documentation

1. Identify user need — Who is the user? (learner or practitioner) What do they need? (do or understand)

2. Apply the compass — Determine which documentation type serves this need

3. Apply principles — Follow the core principles for that type (see above)

4. Check boundaries — Does any part serve a different user need? If yes → split and link

Workflow: Reviewing Documentation

1. Choose a piece — Any page, section, or paragraph

2. Challenge it — What user need does this serve? Which type should it be?

3. Use the compass — If type is unclear, apply the two questions above

4. Identify one improvement — What would help right now?

5. Make that improvement — According to Diataxis principles

6. Repeat — With another piece

Key Principles

• Flow is paramount — Anticipate user needs, minimise context switching
• Boundaries are protective — Keep documentation types separate
• Structure follows content — Don't create empty sections; write what serves real needs
• One need at a time — Each piece serves one user need

Common Mistakes to Avoid

• Tutorial/How-to conflation — Tutorials are for learning; how-to guides are for working
• Over-explaining in tutorials — Trust that learning happens through doing
• How-to guides that teach — Assume competence; don't explain basics
• Reference that instructs — Reference describes; it doesn't tell you what to do
• Explanation in action docs — Move explanation to separate docs and link

If you need more detail

→ resources/principles.md — Comprehensive principles for each documentation type with examples → resources/reference.md — Quality framework, complex scenarios, and additional guidance