Documentation content types
Use the Diátaxis framework to give every page one job — tutorial, how-to guide, reference or explanation.
Documentation pages do different jobs. A tutorial that takes a newcomer through their first deploy has almost nothing in common with the API reference an engineer opens ten times a day. A page that tries to do both does neither well.
The Diátaxis framework sorts documentation by what the reader needs at the moment they open the page. It names four types.
The four types
Section titled “The four types”Diátaxis places the four types on two axes. One axis asks whether the reader is doing something or thinking about something. The other asks whether they are learning or working.
| Learning | Working | |
|---|---|---|
| Doing | Tutorial | How-to guide |
| Thinking | Explanation | Reference |
Tutorials: learning by doing
Section titled “Tutorials: learning by doing”A tutorial teaches by having the reader do something. The reader’s goal is to learn. The tutorial’s goal is to give them one successful experience — not to cover every option or explain every mechanism.
A good tutorial:
- Assumes no prior knowledge of the task
- Walks through one complete, working example from start to finish
- Removes choices: it says exactly what to do instead of offering alternatives
- Marks progress at real milestones — “Your site now builds locally”
- Explains only enough to keep the reader moving
Tutorials are the most expensive type to write and to keep working. They are also the type that most decides whether a new user succeeds at all.
How-to guides: getting a task done
Section titled “How-to guides: getting a task done”A how-to guide gets a reader through one specific task. Unlike a tutorial, it assumes context: the reader knows what they want and needs the steps, not a lesson.
A good how-to guide:
- Names one task in its title and sticks to it
- Assumes the prerequisites are already understood
- Gives a clear sequence of steps with no detours
- Says what to do, not how the system works underneath
The difference is practical. “Getting started with authentication” walks a newcomer through the whole setup. “Rotate your API keys” assumes the reader knows what an API key is and just wants the steps.
Reference: looking something up
Section titled “Reference: looking something up”Reference describes the system, accurately and completely. The reader is not reading from the top and is not trying to learn. They want one fact.
Good reference:
- Puts completeness and accuracy ahead of everything else
- Is scannable, with tables, consistent formatting and short descriptions
- Leaves out explanation and background
- Documents everything, including defaults, limits and edge cases
- Follows the shape of the thing it describes — an API reference follows the API
API references, configuration options and CLI commands are reference. Reed’s own component reference and diagnostics list are examples.
Explanation: understanding why
Section titled “Explanation: understanding why”Explanation deepens understanding. The reader opens it to learn why something works the way it does, not to finish a task.
Good explanation:
- Covers the context and motivation behind a design decision
- Names the tradeoffs and the alternatives
- Connects the concept to the rest of the system
- Takes a position where one is warranted
Architecture overviews, concept pages and “how X works” pages are explanation. A reader who finishes one should not feel instructed. They should understand something they did not before. The “Why a registry” section of Analytics is a small example: it tells you nothing to do and a great deal about why the feature is shaped the way it is.
Choose a type for each page
Section titled “Choose a type for each page”| Question | Tutorial | How-to | Reference | Explanation |
|---|---|---|---|---|
| What is the reader’s goal? | Learn by practice | Solve a specific problem | Find a precise fact | Understand a concept |
| How much do they already know? | Little | Some | A lot | Any amount |
| Is it task-oriented? | Yes, guided | Yes, specific | No | No |
| Is it sequential? | Yes | Usually | No | No |
When a page resists classification, ask what the reader does after reading it. If they finished a task, it is a tutorial or a how-to guide. If they now understand something and may act on it elsewhere, it is explanation. If they found one detail and left, it is reference.
Write each type
Section titled “Write each type”Tutorials
Section titled “Tutorials”Open by saying what the reader will have built or done by the end. Number the stages so progress is visible. Where several approaches work, pick one and say that you picked it.
Reed’s Quickstart uses numbered ## headings for its stages, with each
command in a fenced block directly under its heading. That shape holds up well: the
stages appear in the table of contents, and every command stays copyable. Reed’s Steps
component suits short sequences whose steps are prose, but keep fenced code blocks out of
a Step — MDX parses a fence inside a JSX element differently, which is a common source of
confusing build failures. See MDX pitfalls.
How-to guides
Section titled “How-to guides”Lead with the task in the title: “Configure webhooks”, “Migrate from v1 to v2”. Write from the reader’s side, not the product’s. Cut any context that does not change what the reader types or clicks. Link to explanation and reference for readers who want more.
If every item in an ordered list carries a fenced code block, reed check suggests
Steps instead (DS-D04). Take the hint as a prompt to look again, not as an order: a
list whose items are mostly commands often reads better as numbered headings.
Reference
Section titled “Reference”Organize reference around the thing it describes, not around a user journey. Format every entry the same way. Give every parameter, flag or option a type, a default and a one-line description.
Reed’s ParamField exists for exactly this: it carries name, type, default and
required as props, so each entry renders the same way. See
API reference components.
Explanation
Section titled “Explanation”Start with the question you are answering: “Why does authentication work this way?” or “What is the difference between an organization and a workspace?” Admit that other approaches exist. Explain why the product chose the one it did. Link to how-to guides for readers who want to act on what they learned.
Keep types from drifting
Section titled “Keep types from drifting”- Choose the type before you write. It decides the structure, the length, the tone and what to leave out. Deciding afterwards means rewriting.
- Review mixed-purpose pages. A page that explains a concept, walks through a setup and lists every option at once is hard to use and hard to maintain. Split it, or choose a primary type and move the rest.
- Adapt the framework. Diátaxis is a starting point, not a law. Some products need hybrids. The principle underneath — match the page to what the reader needs right now — applies everywhere.
Frequently asked questions
Section titled “Frequently asked questions”Does every feature need all four types?
No. A small feature may need only a how-to guide and a reference entry. The four types describe needs readers might have, not a checklist. Start with what your readers actually need — usually a how-to guide and reference — and add tutorials and explanation where readers consistently struggle to get started or to understand.
What is the difference between a tutorial and a how-to guide?
A tutorial is a lesson. The reader starts without the knowledge and ends having built something, with the tutorial doing the teaching. A how-to guide is a recipe. The reader knows what they want and needs the steps. “Build your first integration” and “Connect a new integration” can involve the same actions and still serve different readers in different situations.
Can one page be more than one type?
In practice pages often mix types — getting-started pages commonly blend tutorial and how-to. The test is whether the mix helps the reader or confuses them. A page that needs to explain a concept and then walk through setup can work with clear sections. When the content is too tangled to organize cleanly, split it.
How detailed should reference be?
Detailed enough that nobody has to read the source code or ask support what a parameter does. Every configurable value needs a description, a type, a default and an example. Reference that leaves out limits and edge cases forces readers to find them by trial and error. That is a documentation failure, not a user error.
Related pages
Section titled “Related pages”A starting page for each of the four types.
Voice, tone and the sentence-level rules.
Find out who each page is for.
Arrange the pages once each one has a job.