writing-diataxis-documentation

Files (7)

• SKILL.md
• openai.yaml · agents/
• documentation-sets.md · references/
• explanation.md · references/
• how-to-guides.md · references/
• reference.md · references/
• tutorials.md · references/

SKILL.md (first lines)

# Writing Diataxis documentation

Make each document serve one user need at one moment.

## Use the compass

Classify the reader's need along two axes:

- Action + acquisition of skill (study): tutorial.
- Action + application of skill (work): how-to guide.
- Cognition + application of skill (work): reference.
- Cognition + acquisition of skill (study): explanation.

Let the reader's need determine the form. Ignore format, subject, difficulty,
and product features. A basic procedure can be a how-to guide. An advanced
lesson can be a tutorial. Use the reader's study or work context to distinguish
tutorials from how-to guides, even when both contain steps. The same test
separates reference from explanation when both contain theoretical knowledge.

## Apply it

1. Identify the reader's immediate need and relationship to the subject: study
   or work.
2. Choose one quadrant. When the choice is unclear, apply the compass to the
   disputed sentence or section instead of reasoning only at page level.
3. Read only the reference for each form in scope:
   - [tutorials.md](references/tutorials.md)
   - [how-to-guides.md](references/how-to-guides.md)
   - [reference.md](references/reference.md)
   - [explanation.md](references/explanation.md)
4. Split, move, or link material that serves another need. Don't preserve a
   blurred page solely to make it self-contained.
5. For multi-page architecture, migration, or mixed-content review, also read
   [documentation-sets.md](references/documentation-sets.md).
6. Draft or revise in the user's requested format. Diataxis labels don't need to
   appear as headings.
7. Check the result against the chosen quadrant. Check technical accuracy and
   completeness separately.

## Authority

This skill distills the 18 English pages published at https://diataxis.fr/ as of
2026-08-26. Treat the site as authoritative when the methodology changes.

From chadxz/prompts, CC-BY-SA-4.0.

More from chadxz/prompts