The Four Modes of Technical Documentation: A Map for Every Doc You Write
The single most common reason technical documentation fails is not bad writing—it is a page trying to do two jobs at once. A tutorial that keeps stopping to explain architecture loses the beginner. A reference page padded with encouragement wastes the expert's time. Knowing how to write technical documentation starts with knowing which kind of document you are actually writing.
The Diátaxis framework, created by Daniele Procida and now used by teams at organizations like Canonical and Gatsby, names four distinct modes: tutorials, how-to guides, reference, and explanation. Each serves a different reader need along two axes—learning versus working, and practical steps versus theoretical understanding. Get the mode right and structure, tone, and scope fall into place almost automatically. For a broader grounding, start with our beginner's guide to technical writing.
Why Documentation Types Matter
Readers arrive at documentation in one of two states: they are studying to build a skill, or they are working to complete a task. Someone learning your product for the first time needs a guided path with guaranteed success. Someone debugging a production incident at 2 a.m. needs a precise answer and nothing else. When you serve both audiences on the same page, you satisfy neither. Separating documentation by mode is the cheapest quality improvement most teams can make—it requires no new tooling, only discipline about scope.
The four modes also give your team a shared vocabulary. Instead of arguing whether a page is "too long" or "too basic," you can ask a sharper question: "What mode is this, and is it doing that mode's job?" That reframing turns subjective review feedback into something concrete. The official Diátaxis documentation at diataxis.fr is the canonical reference, and it pairs well with the Write the Docs community resources for putting the theory into daily practice.
Tutorials: Learning by Doing
A tutorial takes a complete beginner by the hand and produces a small, visible success. Its measure is not comprehensiveness but confidence: the reader should finish thinking "I did it, and I can do it again." That means the author, not the reader, is responsible for every decision. You choose the example, the sample data, and the exact commands. You do not offer options or caveats, because choices create anxiety and branch points create failure. A good tutorial is a controlled, repeatable experience where success is guaranteed if the steps are followed.
Practically, this means testing your tutorial end-to-end on a clean environment—no cached credentials, no pre-installed dependencies, no assumptions about the reader's setup. State the prerequisites explicitly, show expected output after key steps so readers can confirm they are on track, and keep the total time under thirty minutes. Resist the urge to explain why each step works; a curious learner can follow links to explanation material later. The tutorial's only job is momentum.
How-To Guides: Solving Real Problems
Where a tutorial teaches, a how-to guide assists someone who already knows the basics and now has a specific goal: "configure single sign-on," "migrate from v2 to v3," "set up rate limiting." The reader is competent and in a hurry. The guide should be titled by the goal, start from a realistic assumed state, and present a sequence of actions that reach the outcome. Unlike a tutorial, a how-to can acknowledge alternatives—"if you use Postgres, do X; if MySQL, do Y"—because the reader has the context to choose.
The most common how-to mistake is drifting into reference or explanation. Keep it action-oriented: each step should be a verb the reader performs. Link out to reference pages for exhaustive parameter lists rather than reproducing them inline. A strong how-to library is essentially a catalogue of your users' real problems, which is why reviewing your support tickets is the fastest way to discover which guides you are missing.
Reference: The Source of Truth
Reference documentation describes the machinery: every API endpoint, configuration flag, CLI command, error code, and return value. It is consulted, not read. Its defining qualities are accuracy, consistency, and completeness—readers trust reference material to be exhaustive and never to lie. Because of that, reference is the mode most worth generating from the source of truth wherever possible. API references built from an OpenAPI specification, or config docs generated from annotated schema, stay accurate because they are derived from the same code they describe.
Structure reference for scanning, not narrative. Use consistent templates: name, description, parameters, returns, errors, example. Alphabetize or group predictably. Do not editorialize or teach—an aside like "you'll rarely need this" belongs in explanation, not reference. If you find yourself wanting to add context, that is a signal to write a companion explanation page and cross-link it. For deeper patterns on structuring endpoint docs, see our guide on cost-effective API documentation.
Explanation: Understanding the Why
Explanation—sometimes called conceptual or discussion documentation—illuminates the reasoning behind the product: architecture decisions, trade-offs, background, and the mental model that makes everything else make sense. It is the mode readers turn to when they want to understand rather than do. Unlike the other three, explanation can be read away from the keyboard, over coffee. It is allowed to consider alternatives, admit history, and connect your product to broader ideas.
Good explanation answers "why is it built this way?" and "how should I think about this?" It is where you discuss the CAP theorem trade-offs your database made, or why your API uses cursor-based pagination instead of offsets. Because explanation is the least urgent mode, teams under-invest in it—yet it is often what separates documentation readers merely tolerate from documentation they genuinely trust. To develop this skill deliberately, our Documentation Architecture course at Darlo walks through mapping an entire product's docs to the four modes, and includes a downloadable content-audit template you can run against your existing site this week.
Mixing Modes Without Confusing Readers
Real documentation sets are not four monolithic sections; they are dozens of pages, each ideally committed to one mode, densely cross-linked. The art is in the linking. A tutorial ends by pointing to relevant how-to guides. A how-to guide links to reference for exhaustive detail and to explanation for the reasoning. A reference entry links back to the how-to that shows it in context. This web lets each page stay short and single-purpose while the reader still finds everything they need.
When you inherit a sprawling page that mixes modes, split it. Extract the numbered steps into a how-to, move the parameter table into reference, and lift the background into an explanation page. Readers almost always prefer three focused pages to one exhausting one. Adopt the four modes as a review checklist—every new page should answer "which mode am I?" before it merges—and your documentation quality will rise steadily without any new tools. Pair this with the plain-language habits in our clear-communication guide and each page will be both correctly scoped and easy to read.
The Documentation Content Audit Template
A ready-to-use spreadsheet that maps every page in your docs to one of the four modes—tutorial, how-to, reference, explanation—so you can spot mixed-purpose pages and gaps in minutes.
Do I need all four documentation types for a small project?
No. Small projects often thrive with a solid README (a light tutorial), a handful of how-to guides, and a reference. Add explanation as the project grows and readers start asking "why." The value is in keeping each page single-purpose, not in producing all four upfront.
What is the difference between a tutorial and a how-to guide?
A tutorial teaches a beginner through a guaranteed, controlled success and takes full responsibility for every choice. A how-to guide assists a competent user pursuing a specific real-world goal and may offer alternatives. Tutorials build skill; how-tos solve problems.
Where does API reference documentation fit?
API reference is pure reference-mode content: exhaustive, accurate, and consulted rather than read. Generate it from an OpenAPI spec where possible so it stays in sync with the code, then link to how-to guides and explanation pages for context.