Diátaxis
A runbook for producing and fixing technical documentation with the Diátaxis framework. Diátaxis splits documentation into four modes — tutorials, how-to guides, reference, explanation — because they answer four different user needs that pull in opposite directions. The single idea that makes it work:
Most documentation problems are a single thing: content that tries to serve more than one need at once. Separate the four modes and most confusion dissolves.
Diátaxis is descriptive, not prescriptive — a way to understand documentation, not a template to fill in. Don't wait to understand the whole framework before applying it: pick one small thing, classify it, improve it, publish, repeat.
When to Apply
Use this skill when:
- Writing or generating new documentation of any kind (README, API docs, guide, onboarding, developer docs) — decide which mode(s) the content needs before writing it.
- A page is confusing, bloated, or "tries to do everything" — diagnose the type-mixing and split it.
- Users can't get started, can't complete a task, can't find a fact, or don't understand why — locate the missing or weak mode.
- Restructuring or auditing an existing doc set — apply the small-step workflow instead of a big rewrite.
- You're unsure whether something is a tutorial, how-to, reference, or explanation — run the compass.
Do not reach for this skill for pure prose/copy-editing within an already-correct mode (use a copywriting skill), or for design/spec/proposal documents — those are mostly explanation and are better served by dev-rfc or feature-spec.
The four modes
Each mode serves a different user, in a different situation, with a different content style. The quickest way to keep them straight:
| Mode | Serves | Oriented to | Analogy | Answers |
|---|---|---|---|---|
| Tutorial | a beginner learning | learning, study | teaching a child to cook | "teach me, by doing" |
| How-to guide | a user working | a goal, a task | a recipe in a cookbook | "how do I achieve X?" |
| Reference | a user working | information | an encyclopaedia entry | "what is X exactly?" |
| Explanation | a user studying | understanding | an article about cooking | "why is X this way?" |
Two of them serve practical steps (tutorial, how-to); two serve theoretical knowledge (reference, explanation). Two serve someone acquiring skill / studying (tutorial, explanation); two serve someone applying skill / working (how-to, reference).
The compass — decide what you are writing
When you are unsure which mode a piece of content belongs to, answer two questions. This is the master decision tool; the full tree is in compass-tree.md.
1. Does it inform action or cognition? — practical steps (doing) vs theoretical knowledge (thinking). 2. Does it serve acquisition or application? — study (learning) vs work (applying what you know).
| Action (practical steps) | Cognition (theoretical knowledge) | |
|---|---|---|
| Acquisition (study / learning) | Tutorial | Explanation |
| Application (work / doing) | How-to guide | Reference |
Read as a decision: informs action + serves acquisition → tutorial; informs action + serves application → how-to guide; informs cognition + serves application → reference; informs cognition + serves acquisition → explanation. Apply the compass at any scale — a whole document, a section, or a single sentence that has drifted into the wrong mode.
Common Symptoms
Start here. Match the situation, open its tree. Severity reflects how badly the reader is failed right now (see symptoms.md).
| Symptom / trigger | Likely problem | Tree |
|---|---|---|
| "Write docs for X" / "document this" — and it's unclear what kind of doc | No mode chosen yet — classify first | compass-tree |
| A page feels bloated, rambling, or mixes teaching + steps + specs + opinion | Type-mixing — two needs in one document | wrong-type-tree |
| Beginners can't get started · competent users can't finish a task · people can't find a fact · users don't understand why | A missing or weak quadrant | gaps-tree |
| "Our docs are a sprawling mess — where do I even start?" | Needs the iterative workflow, not a rewrite | restructure-tree |
How to use
- Match the symptom in the table above and open its tree in
references/. For a large existing corpus, runbash references/queries/scan-docs.sh <docs_root>first — it triages which pages show signals of more than one mode, so you know where to point the compass. - Classify with the compass — decide which of the four modes the content serves. When in doubt, open compass-tree.md.
- Read the matching type guide — tutorials, how-to-guides, reference, or explanation — for how to write that mode well, and what to keep out of it.
- Work in small steps. Follow workflow.md: choose something small → assess it → decide one next action → do it and publish. Never tear everything down to restructure top-down.
- Assess against quality. Use quality.md to judge functional quality (accuracy, completeness, consistency) and deep quality (does it feel good to use, anticipate the user's needs).
- Record an audit with assets/templates/report.md when reviewing an existing doc set, so the same gaps don't get re-litigated each time.
Setup
This skill uses an optional config.json to know where your docs live and where to log audits. On first use, if docs_root is empty and you are auditing an existing doc set, ask the user (via AskUserQuestion) for the documentation directory, then save it. The skill works without config — fall back to asking inline. Never block on missing config.
Gotchas
The recurring traps of applying Diátaxis — empty structure-first scaffolding, "balancing" the four types instead of separating them, explaining inside a tutorial — are in gotchas.md. Read it before your first restructure.
Related skills
skill-authoring— authoring Agent Skills; their SKILL.md is itself a Diátaxis problem (navigation + reference, not a tutorial).human-copywrite/humanize— once a doc is in the right mode, these tighten the prose so it reads naturally.dev-rfc/feature-spec— design and spec documents are mostly explanation; reach for those when the artifact is a proposal, not user documentation.