The single most useful mental model in the whole craft is Diátaxis, which splits documentation into four types according to what the reader is doing when they arrive. Get the type right and the page almost writes itself, because the type tells you the voice, the shape, and the test for ‘done’. Get it wrong and no amount of careful writing will rescue the page — the reader will simply feel that something is off.
The four types
- Tutorial — learning-oriented. A guided first experience that guarantees a beginner an early win. It holds the reader’s hand and takes responsibility for their success.
- How-to guide — task-oriented. Helps a competent user complete one specific goal. It assumes the basics and gets straight to the point.
- Reference — information-oriented. Describes the machinery precisely and completely, for lookup. Terse, consistent, exhaustive, and dependable.
- Explanation — understanding-oriented. Provides background, context and the ‘why’ behind decisions. It is the one you read in an armchair, not at the keyboard.
Notice that the four split along two axes: whether the reader is studying or working, and whether they need practical steps or theoretical knowledge. Tutorials and how-tos are practical; references and explanations are theoretical. Tutorials and explanations suit study; how-tos and references suit work. Every page sits in one of those quadrants — and trouble starts the moment a page tries to sit in two.
Which type is each of these?
- ‘Build your first integration in 10 minutes’
- ‘All configuration options for the CLI’
- ‘Why we chose eventual consistency’
- ‘Rotate a leaked API key’
Answers: Tutorial; Reference; Explanation; How-to guide. If you found those easy, you already have the instinct that most doc sets are missing.
Why mixing them hurts
Each type has a different voice, shape and success test, and they actively work against each other. A tutorial that stops to enumerate every edge case loses the beginner it was meant to carry. A reference that lapses into friendly tutorial prose becomes impossible to scan when you just need a parameter. An explanation crammed into a how-to buries the steps under theory. The single most common documentation failure is not bad writing — it is one page trying to be all four things at once. When a page feels confusing despite being ‘well written’, the fix is almost always to split it by type and cross-link the pieces.
Use it as a diagnostic and a planning tool
The model earns its keep in two ways. As a diagnostic: take any confusing page you already have and ask ‘what is the reader doing here — learning, doing, looking up, or understanding?’ If the honest answer is ‘more than one of those’, that’s your bug. As a planning tool: for each task on the map you built last lesson, decide which type of page it needs, and you’ll often find you need two — a how-to and the reference it leans on.
Imagine a single page titled ‘Webhooks’ that opens with three paragraphs on event-driven architecture, then a tutorial for your first webhook, then a table of every event type, then troubleshooting. It’s exhausting because it’s all four types at once. Split it: an explanation (‘How webhooks work’), a tutorial (‘Receive your first webhook’), a reference (‘Webhook event types’), and a how-to (‘Verify a webhook signature’) — each short, each with one job, all cross-linked. Same content; night-and-day usability.
In the age of AI
The type is the single most valuable instruction you can give an AI. ‘Write a reference entry for this endpoint’ produces something dramatically more usable than ‘write docs for this endpoint’, because the type encodes voice, shape and scope in one word. Learn the four types well and you gain two things at once: pages that serve real readers, and a vocabulary precise enough to make AI genuinely useful. Over the rest of the course we build each type deliberately, starting with the one developers reach for most — the API reference.
Answer, then press Check. Explanations appear after.
Select allWhich of these are the four Diátaxis documentation types? (Select all that apply.)
Choose oneA beginner’s guided first success belongs in a…