diataxis

What this skill does

# Diátaxis documentation framework

You write and review documentation according to the Diátaxis framework by
Daniele Procida (https://diataxis.fr). Diátaxis identifies four modes of
documentation, each serving a distinct user need. **Never mix modes within a
single document.**

The source material in `${CLAUDE_SKILL_DIR}/diataxis-documentation-framework/`
is the RST source of the Diátaxis website itself. It is structured according to
its own principles: the pages on each documentation type are reference, the
compass and workflow pages are how-to guides, the foundations and map pages are
explanation, and the start-here page is a tutorial. Study the source not just
for what it says, but for how it's written.

## The compass: classifying content

Ask two questions to determine which mode content belongs to:

| Content...        | ...serves the user's... | ...belongs to |
|-------------------|-------------------------|---------------|
| informs action    | acquisition of skill    | tutorial      |
| informs action    | application of skill    | how-to guide  |
| informs cognition | application of skill    | reference     |
| informs cognition | acquisition of skill    | explanation   |

## The four modes at a glance

**Tutorial** — a lesson. Learning-oriented. The reader acquires skill by doing
things under your guidance. You are the teacher; all responsibility for success
is yours. Minimize explanation. Focus on concrete steps and visible results.

**How-to guide** — a recipe. Goal-oriented. The reader already has competence
and needs to accomplish a specific real-world task. No teaching, no explanation.
Address the user's problem, not the tool's features.

**Reference** — a map. Information-oriented. Austere, neutral, complete
technical description of the machinery. Structure mirrors the thing it
describes. One consults reference; one does not read it.

**Explanation** — a discussion. Understanding-oriented. Provides context,
background, reasoning, and connections. Answers "why?" questions. The only mode
where opinion, alternatives, and history belong.

## When to read the source material

Read the relevant page before writing or reviewing documentation of that type.
All paths are relative to `${CLAUDE_SKILL_DIR}/diataxis-documentation-framework/`.

| Task | Read |
|------|------|
| Quick overview of the framework | `start-here.rst` |
| Writing or reviewing a tutorial | `tutorials.rst` |
| Writing or reviewing a how-to guide | `how-to-guides.rst` |
| Writing or reviewing reference docs | `reference.rst` |
| Writing or reviewing explanatory docs | `explanation.rst` |
| Unsure what type of doc to write | `compass.rst` |
| Distinguishing tutorials from how-tos | `tutorials-how-to.rst` |
| Distinguishing reference from explanation | `reference-explanation.rst` |
| Organizing a large documentation set | `complex-hierarchies.rst` |
| Understanding the theory behind Diátaxis | `foundations.rst`, `map.rst` |
| Thinking about documentation quality | `quality.rst` |
| Workflow: applying Diátaxis iteratively | `how-to-use-diataxis.rst` |

**Do not read HTML files or images.** The canonical source material is the `.rst`
source files, and all other files in the source are of limited value for your
comprehension of the framework.

## Applying this skill

When asked to write documentation:

1. **Classify** the content using the compass table above.
2. **Read** the relevant source page for the mode you're writing in.
3. **Write** following the principles in that page.
4. **Verify** that you haven't mixed modes. If a section drifts into another
   mode (e.g., explanation creeping into a how-to guide), split it out or
   remove it.

When asked to review documentation:

1. **Classify** each section by mode.
2. **Read** the relevant source pages.
3. **Assess** whether each section follows the principles for its mode.
4. **Report** mode violations, mixed content, and structural issues.

$ARGUMENTS