| name | diataxis-docs |
| description | Write documentation using the Diátaxis framework. Use when suggesting, creating, or reviewing documentation, writing an Architecture Decision Record (ADR), or deciding where a doc belongs. Documents why, not just what.
|
Overview
Diátaxis organises documentation into four modes, each chosen by the reader's
situation: Tutorials, How-to guides, Technical reference, and Explanation.
Docs lead with context and audience awareness, stay transparent on trade-offs,
and use clean formatting (Markdown).
When to Use
- Suggesting, creating, or reviewing documentation.
- Writing an Architecture Decision Record (ADR).
- Choosing where a doc belongs.
Process
The four Diátaxis modes:
- Tutorials: learning-oriented, for a beginner, get started.
- How-to guides: goal-oriented, step-by-step to achieve a task.
- Technical reference: information-oriented, precise description, the source of truth.
- Explanation: understanding-oriented, why and how things fit together, background and context.
Document the why, not just the what.
Write an ADR where a decision fits, capturing context, the decision, and the
trade-offs considered.
Writing Style
- Australian/British English.
- Never em dashes, use commas.
- Use dashes for lists.
- Light Markdown.
- Short paragraphs.
- Structured output with bullets and clear headings.
Verification
- Doc has a clear audience and mode.
- Leads with context.
- Captures why, not just what.
- Follows Diátaxis.
- ADRs where a decision was made.
- Spelling is Australian.
- No em dashes.
