Diátaxis for Technical Writing: The Framework Behind Great Docs

April 20, 2026 18 min read Software Architecture

documentationtechnical-writingdiataxisdeveloper-experienceengineering-practices

Contents

You can tell the moment a documentation site was designed by committee. There’s a “Getting Started” page that assumes you already understand the system. There’s a reference that reads like a tutorial halfway through. There’s a “Guide” page that mixes conceptual background, step-by-step instructions, and a list of every option the function accepts. Users land on it, skim for thirty seconds, give up, and open an issue asking a question the docs theoretically answer.

The problem isn’t that the writing is bad. The problem is that four fundamentally different types of documentation have been jammed into the same pages. Diátaxis — a framework developed by Daniele Procida and now adopted by the Python docs, Django, Cloudflare, GitLab, and a long list of others — is the clearest articulation of why that happens and what to do about it.

The core claim is simple: there are exactly four kinds of technical documentation, they serve different user needs, and mixing them produces docs that fail every reader simultaneously. Separate them, write each one with its own voice and structure, and the whole corpus gets better.

This post is the practical guide. What the four quadrants are, how to tell them apart when you’re writing, what each one actually looks like, how to structure a docs site around them, and the common failure modes when teams try to adopt the framework.

The four modes

Diátaxis organizes documentation along two axes:

Practical vs theoretical: Is the doc about doing something or about understanding something?
Acquisition vs application: Is the user learning (studying to grow capability) or working (using the tool to accomplish a task)?

Cross those axes and you get four quadrants:

	Practical (action)	Theoretical (cognition)
Acquisition (study)	Tutorials — learning-oriented	Explanations — understanding-oriented
Application (work)	How-to guides — task-oriented	Reference — information-oriented

Each quadrant answers a different user question:

Tutorial: “Teach me.” I’m new. Take me by the hand and show me something working.
How-to: “Help me do X.” I know roughly what I’m doing and I need to accomplish a specific task.
Reference: “Tell me exactly what this is.” I need the precise facts — flags, parameters, return values, error codes.
Explanation: “Help me understand.” I want the background, the rationale, the mental model.

The critical insight is that these are different documents with different contracts with the reader. A tutorial that pauses to explain the CAP theorem has broken its contract. A reference page that tries to teach is useless as a reference. An explanation that walks through setup is unreadable as background. Good docs respect the mode.

Tutorials: the most misunderstood quadrant

Tutorials are the hardest mode to write well, and most teams get them wrong. A tutorial is a lesson. The goal is not to accomplish real work — it’s to produce the experience of learning by doing something concrete. The reader leaves with confidence and a rough mental model, not a production system.

What tutorials are:

Learning-oriented. The aim is the user’s capability, not the user’s output.
Guaranteed to work. Every command runs. Every output matches. Nothing is an exercise for the reader.
Concrete. Build a specific thing. Not “configure authentication” — build a todo app with a login page.
Hand-holding. Zero assumed context beyond stated prerequisites. If you skip a cd, the tutorial is broken.
Minimal explanation. When you explain, explain briefly and forward — “we use --network=host here for reasons we’ll cover later.” The tutorial is not the place for depth.

What tutorials are not:

A walkthrough of every feature.
A tour of the codebase.
A list of “things to try.”
A real-world example. A tutorial is a toy, intentionally.

The test: a beginner can follow your tutorial on a fresh machine, type every command exactly as shown, and end up with a working thing. If any step requires them to think, improvise, or fill in a blank, the tutorial is broken.

A good tutorial is astonishingly hard to write because it requires discipline. The subject-matter expert writing it knows too much; their instinct is to explain, to mention caveats, to show the “right” way. Tutorials reward restraint. The Django tutorial — a canonical example — builds a tiny polls app. It’s not good Django. It’s not even idiomatic. It’s a vehicle for the learner’s first success.

Tutorial writing checklist

Does it build exactly one concrete thing?
Does every command work on a fresh environment?
Have you tested it end-to-end recently? (Tutorials rot the fastest.)
Is every prerequisite stated upfront?
Did you avoid optional branches, “you could also,” and “alternatively”?
Did you avoid deep explanation?

How-to guides: the workhorses

A how-to guide helps a competent user accomplish a specific task. They already know the basics. They’re not here to learn — they’re here to get a job done and leave.

What how-tos are:

Task-oriented. Each guide solves one problem: “Deploy to Kubernetes.” “Configure TLS with Let’s Encrypt.” “Migrate from v2 to v3.”
Goal-focused. The guide starts with the goal and ends when the goal is achieved.
Assumes competence. The reader knows what a container is. The reader can read a YAML file.
Addresses real-world messiness. Unlike tutorials, how-tos can say “if you’re behind a proxy, do this; if not, skip to step 4.”
Scannable. Users read how-tos to get unstuck fast. Headings, numbered steps, and code blocks beat prose.

What how-tos are not:

Tutorials. (A how-to doesn’t teach — it assumes capability.)
Reference. (A how-to doesn’t list every option — it tells you which option to use for this task.)
Explanation. (A how-to doesn’t argue why — it shows how.)

The name of a how-to should always start with a verb and state the goal: “How to configure SAML SSO”, “Deploy a Hugo site with GitHub Pages”, “Rotate your database credentials”. If the title is a noun (“Authentication”), it’s not a how-to.

How-tos are where Diátaxis pays its biggest dividend. Most teams’ “documentation” is actually a pile of how-tos masquerading as everything else — tutorials that skip steps, references that lack precision, explanations that are really checklists. Explicitly labeling a document as a how-to forces it to be a how-to, which is usually what it was trying to be anyway.

How-to writing checklist

Does the title start with a verb and state a specific goal?
Is the reader’s starting state stated? (Assumed knowledge, installed prerequisites, system state.)
Does the guide end when the goal is achieved, not when the author runs out of things to say?
Are branches (“if X, then Y”) used where real-world variation exists?
Have you resisted the urge to explain why? (Link to the explanation instead.)

Reference: the authoritative index

Reference is the dry, precise, exhaustive documentation that tells you exactly what something is. Every flag. Every parameter. Every return code. Every field of every configuration object. No commentary, no opinions, no narrative.

What reference is:

Information-oriented. The goal is to state facts, nothing more.
Exhaustive. If it’s part of the public surface, it’s documented.
Structured. Consistent formatting, predictable layout. Users skim reference — structure is the feature.
Authoritative. Reference is the source of truth. If reference contradicts a how-to, reference wins.
Often generated. API references, CLI references, schema references — generated from source and never edited by hand.

What reference is not:

A tutorial (“here’s how you’d use this function to build…”).
A how-to (“use this when you need to…”).
An explanation (“this function exists because…”).

The test: can a reader look up exactly what they need without reading anything else? Reference is accessed by search and index, not read front-to-back. It succeeds when it answers specific questions fast.

A common trap: decorating reference with narrative. “The timeout parameter controls how long the request will wait before giving up. Timeouts are important because networks are unreliable, and you should…” Stop. The reference is timeout: integer, seconds before the request is abandoned. Default: 30. The rest belongs in an explanation.

Reference writing checklist

Is the structure consistent across every reference entry? (Same fields, same order.)
Is it exhaustive? (No “undocumented” features.)
Is it precise? (Types, defaults, units, constraints.)
Is narrative banned? (Use explanations for narrative.)
Can it be generated from source to avoid drift?

Explanation: the conceptual layer

Explanation is the documentation that helps users understand. Why this architecture. What tradeoffs the designers chose. How pieces relate. Background a user needs to reason about the system, not just operate it.

What explanation is:

Understanding-oriented. The goal is the reader’s mental model.
Discursive. It’s OK to be long. It’s OK to have opinions.
Connective. Relates concepts to each other and to external context.
Non-procedural. Don’t include steps. Don’t even include commands if you can help it.
Read for background. The reader has time. They want depth.

What explanation is not:

A how-to with commentary.
A tutorial dressed up as a concept page.
Reference with editorial asides.

Good explanation answers questions like:

Why does the scheduler use this algorithm and not that one?
How does the consistency model interact with our replication strategy?
What’s the relationship between roles, policies, and groups in our auth model?
Why did we choose Postgres over MongoDB? (This is often where ADRs and explanation intersect.)

Explanation is the quadrant most likely to not exist in a given project. Engineers are comfortable writing reference and how-tos — they’re close to the code. Tutorials, when they exist, are usually maintained. But the “why” and “how this works conceptually” often lives in tribal knowledge, Slack threads, or not at all. Filling this gap is one of the highest-leverage documentation investments a team can make.

Explanation writing checklist

Does it stand on its own as reading? (Can a reader sit down with coffee and learn?)
Does it connect concepts, not just describe them?
Does it acknowledge tradeoffs and alternative designs?
Does it avoid step-by-step instructions?
Does it link out to the how-to or reference rather than inline them?

The compass: where am I?

Procida’s “Diátaxis compass” is a practical trick for authors. When you’re about to write (or revise) a doc, ask:

Is the user acting or thinking?
Is the user learning or working?

That single question identifies the quadrant. You can also run it in reverse on existing docs — pick a page, ask the question, and notice when the page is trying to be two quadrants at once.

A simpler version: what’s the reader’s question?

“I’m new — teach me.” → Tutorial
“Help me with this specific task.” → How-to
“What are all the options?” → Reference
“Why does this work the way it does?” → Explanation

If a page is answering two of those questions at once, split it.

A worked example: authentication docs

Consider a product that supports multiple auth methods. Here’s what a traditional docs page might contain:

Authentication

Our platform supports several authentication methods including OAuth, SAML, and API keys. OAuth is based on the OAuth 2.0 standard (RFC 6749) and is appropriate for web applications with user-facing login flows. To set up OAuth, first create a client application in the admin console, then…

That’s three documents mashed together: an explanation of auth methods, a how-to for OAuth setup, and the implicit promise of reference (all methods). Under Diátaxis you’d restructure into:

Tutorial: Get Your First User Logged In. A complete, concrete walkthrough using a specific auth method (probably the simplest). Beginner-level; builds a working login flow in a toy app.
How-to: How to Configure OAuth. Dry, task-focused. How to Configure SAML. How to Rotate an API Key. How to Migrate from API Keys to OAuth.
Reference: Authentication API Reference. Every endpoint, every parameter, every error code, every scope. Probably generated from OpenAPI.
Explanation: Authentication Concepts. The auth model: principals, roles, tokens. When to use OAuth vs SAML vs API keys. The security properties of each. How session management works.

The reader looking for quick OAuth setup finds the how-to. The engineer doing a security review reads the explanation. The SDK author lives in the reference. The newcomer starts with the tutorial. Nobody has to read everything to get what they need, and every piece of writing has a clear job.

Structuring a docs site

Diátaxis works best as a top-level site structure. The canonical layout:

docs/
├── tutorials/
│   └── your-first-app.md
├── how-to/
│   ├── deploy-to-kubernetes.md
│   ├── configure-tls.md
│   └── migrate-from-v2.md
├── reference/
│   ├── api/
│   ├── cli.md
│   └── configuration.md
└── explanation/
    ├── architecture.md
    ├── consistency-model.md
    └── auth-concepts.md

This structure forces authors to pick a mode before they start. “Where does this go?” becomes the first editorial question. If the answer is “I don’t know” — the doc probably belongs in two places and needs to be split.

The four-quadrant structure should be visible in your site navigation. Don’t bury it. The Django docs and the Python docs both expose this top-level division, and users learn to navigate by mode within a few visits.

Categories that look like modes but aren’t

Many docs sites have sections like:

“Getting Started” — usually a mix of tutorial, how-to, and explanation. Split it.
“Guides” — almost always a bucket for “things that aren’t reference.” Apply the compass to each one.
“Concepts” — often correct as explanation, but sometimes hides how-tos.
“API” — usually genuine reference.
“FAQ” — often a symptom. FAQs are admissions that the docs didn’t answer questions upstream. Either route the answer back to tutorial/how-to/explanation, or keep the FAQ as a small navigation layer.

Metadata helps

Tag each doc file with its mode in frontmatter:

1
2
3
4


---
title: How to Configure TLS
diataxis: how-to
---

This seems like busywork until you have two hundred doc pages and need to check — are our explanations actually explanations? A lint rule over the docs tree can now flag a how-to that contains prose without numbered steps, or a reference page that lacks a consistent field layout.

Common failures when adopting Diátaxis

“We already have tutorials” (they’re how-tos)

The most common failure. A team looks at their existing docs, sees “Getting Started with Kafka,” and labels it a tutorial. But the page skips steps, assumes Kafka is already installed, and lists options rather than walking through a specific build. That’s a how-to with a tutorial-shaped label. Apply the tutorial test: can a true beginner follow it on a fresh machine? If not, it’s not a tutorial.

The reference is contaminated with opinions

Reference pages that say “we recommend…” or “you should probably…” are violating the reference contract. Opinions belong in explanations or how-tos. If the recommendation is strong enough that reference needs to mention it, it belongs as a default: value or a WARNING: callout, not as prose.

Explanations become hidden how-tos

Someone writes “Understanding Our Deployment Model” and halfway through it starts listing commands. The explanation died; a how-to hatched inside it. This happens because engineers are more comfortable writing procedures than prose. Split as soon as you notice.

Every doc has all four modes

The doc page is titled “Authentication.” It opens with concepts (explanation), walks through setup (how-to), mentions every config option (reference), and ends with a toy example (tutorial). Pick one mode per page. If the user journey genuinely crosses modes, link — don’t inline.

Diátaxis theater

Sites that have tutorials/, how-to/, reference/, explanation/ folders but the content inside ignores the split. The directory names alone don’t do the work. The discipline is in what each document contains and refuses to contain.

Treating the four modes as “steps”

A common misread: “Users read tutorials first, then how-tos, then reference, then explanation.” No. The modes aren’t a funnel — they serve different needs from different users at different times. A senior engineer on their first day will read explanations. A beginner on their first day will read a tutorial. An experienced user in production will hit reference. Different doors for different visits.

Over-applying to tiny projects

A project with ten pages of docs may not need four folders. The framework scales down: even for small projects, ask the compass question per page. But you may not need the full directory structure until the corpus grows.

Where ADRs fit

An ADR (Architecture Decision Record) is almost always an explanation in Diátaxis terms. It describes context and consequences, names tradeoffs, and records why a decision was made — pure understanding-oriented content. It’s worth being explicit about this because teams adopting both practices sometimes try to file ADRs elsewhere (“is this a how-to?”). They aren’t. They’re explanation, written in a specific template, living alongside the code.

Linking from explanation pages to the underlying ADRs is the ideal pattern. The explanation says “our consistency model trades off write availability for read correctness”; a “Decisions” section links to ADR-0023: Consistency Model Tradeoff with the full context of when and why.

Tooling around Diátaxis

Diátaxis doesn’t prescribe tools. It’s a framework, not a system. But several tools align naturally:

Sphinx + Read the Docs is the default choice for Python-adjacent projects. The Python docs themselves are Diátaxis-compliant.
MkDocs with Material gives you the top-level navigation structure naturally and supports tags.
Docusaurus and Astro Starlight are good fits for larger sites with versioning and search.
OpenAPI / Redoc or Stoplight for generated API reference.
Vale as a prose linter with rules that can enforce mode-specific style (banned words in reference, required numbered steps in how-tos).
Log4brains and adr-tools for the ADR subset of explanation.

The tooling is interchangeable. The framework is not.

Measuring whether docs are working

Diátaxis gives you a diagnostic lens for complaints:

“The docs are confusing” → users couldn’t find the right mode. Your navigation doesn’t expose the split, or your pages blend modes.
“Setup is hard” → the tutorial doesn’t work. Probably skipped steps or stale commands.
“I can’t find the option” → reference is incomplete or unscannable.
“I don’t understand why it’s designed this way” → explanation is missing.
“I did exactly what the docs said and it didn’t work” → probably a how-to that was written as a tutorial and skipped a real-world branch.

Support tickets and Discord questions are data. Categorize them by the Diátaxis quadrant that should have answered them, and you’ll quickly see which part of your docs is failing.

Getting teams to adopt it

Start with naming. Before writing any new doc, name which quadrant it belongs to. This single habit rewires a team’s intuition.
Audit, don’t rewrite. Walk through existing docs, tag each with a mode, and note which ones blend. You don’t need to fix them all at once — the list is the roadmap.
Split the worst offenders first. The “Getting Started” page that tries to be everything is usually the highest-value target.
Ban FAQ sprawl. FAQ items are usually the lint: each one points to a gap in tutorial, how-to, or explanation.
Review docs in the PR. Treat doc changes like code changes. A reviewer asking “is this really a how-to? It reads like explanation” is the framework doing its job.
Write reference last. Reference is the most mechanical and often the most generate-able. Spending human time there is usually the lowest leverage. The scarce writing skill — clear tutorials and honest explanations — belongs on the other quadrants.
Don’t be precious. Diátaxis is a framework, not a religion. A page that’s 90% how-to with two sentences of context is still fine. The goal is better docs, not purity.

The hidden benefit: it’s easier to write

The quiet reason Diátaxis works isn’t just that readers find the right document. It’s that authors face a smaller blank page. “Write the docs” is an infinite task. “Write a tutorial for setting up a first project” is a finite, bounded task with a clear voice and a clear end. The framework shrinks the job into pieces that fit in a person’s head.

Teams that struggle to write docs often struggle because every page is shaped like every other page — vaguely authoritative, vaguely tutorial, vaguely conceptual — and that ambiguity produces writer’s block and mediocre output. Constraining each document to one mode, with its own conventions and its own contract with the reader, is a productivity tool as much as a user-experience tool.

Closing

Good documentation is a UX problem, not a writing problem. Diátaxis is the clearest framework anyone has produced for the structural half of that problem — the architecture of a docs corpus, not the prose of any one page. Get the architecture right and the writing gets easier. Get the architecture wrong and no amount of prose polish will save you.

Like most frameworks that feel obvious after you’ve seen them, Diátaxis takes real discipline to apply. The temptation to write the one “complete” page about a topic is strong, and the path of least resistance is to let every doc slide toward being a blurry mix of modes. Resist. Name the mode. Write the doc that serves one reader with one need. Link to the others.

Your users will never thank you for using Diátaxis. They’ll just find the answers they need and stop opening tickets. That’s the framework working as intended.