Apply the Diataxis framework to create or improve technical documentation. Use when writing tutorials, how-to guides, reference docs, or explanations.
Creates documentation that "feels good to use" by applying Diataxis, a framework that identifies four distinct documentation types based on user needs and context.
Documentation serves practitioners based on two key dimensions:
1. Action vs Cognition — Doing things vs understanding things 2. Acquisition vs Application — Learning vs working
These create exactly four documentation types:
| Acquisition (Learning) | Application (Working) |
|---|
| Action | Tutorials | How-to Guides |
| Cognition | Explanations | Reference |
When uncertain which type you need, answer two questions:
Does this inform ACTION or COGNITION?
Does it serve ACQUISITION or APPLICATION?
Then apply the matrix above.
Identify user need — Who is the user? (learner or practitioner) What do they need? (do or understand)
Apply the compass — Determine which documentation type serves this need
Apply principles — Follow the core principles for that type (see above)
Check boundaries — Does any part serve a different user need? If yes → split and link
Choose a piece — Any page, section, or paragraph
Challenge it — What user need does this serve? Which type should it be?
Use the compass — If type is unclear, apply the two questions above
Identify one improvement — What would help right now?
Make that improvement — According to Diataxis principles
Repeat — With another piece
→ resources/principles.md — Comprehensive principles for each documentation type with examples
→ resources/reference.md — Quality framework, complex scenarios, and additional guidance