diataxis-docs

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.