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.