| name | diataxis-docs-writer |
| description | Write or improve software documentation using the Diátaxis framework — four documentation types (tutorials, how-to guides, reference, explanation), each serving a different user need. Use it whenever you're about to write or revise documentation for a finished feature, implementation, API, library, CLI, service, or project — READMEs, /docs pages, guides, API/config reference, conceptual overviews — even when the user just says "document this" or "write docs." Especially reach for it right after a feature or PR lands and documentation is the next step, and whenever asked to organize, audit, or improve an existing doc set. It helps you pick the right kind of doc, write each in its correct mode, ground every claim in the actual code, and avoid blurring the four types — the most common documentation failure. Do not use it for in-code docstrings or type hints, debugging, summarizing text, code review, proposing or designing something new (e.g. an RFC), or looking up a library's existing docs. |
Diátaxis documentation
Good documentation is not one thing. It is four things, each answering a
different question a user has, each written in a different way. Most bad
documentation is bad not because the writing is poor but because two of these
four got mixed together — a tutorial clogged with explanation, a reference page
that wanders into opinion, a "how-to" that's really a half-finished lesson.
Your job with this skill is to keep them separate. Decide which kind you're
writing, commit to its discipline, and link out to the others rather than
bleeding into them.
Diátaxis is a guide, not a plan. You don't start by building four empty
sections and filling them in. You write each piece well, in its proper mode,
and good structure emerges from that.
The two axes (why there are exactly four)
Every craft involves two distinctions. Documentation must serve both sides of each:
- Action ↔ Cognition — is the content about doing (practical steps) or about knowing (theoretical facts and ideas)?
- Acquisition ↔ Application — does it serve the user at study (learning the craft) or at work (applying it to get something done)?
Cross those two axes and you get four quadrants — the four documentation types.
There can't be three or five; the two axes define the whole territory.
Step 1 — Classify before you write (the compass)
Before writing a sentence, decide which type you're producing. Ask just two questions:
- Action or cognition? (Is this about what the user does, or what they know?)
- Acquisition or application? (Is the user studying, or working?)
| If the content informs… | …and serves the user's… | …then it is a… | It answers | Its form is |
|---|
| action | acquisition (study) | Tutorial | "Can you teach me to…?" | a lesson |
| action | application (work) | How-to guide | "How do I…?" | a recipe |
| cognition | application (work) | Reference | "What is…? / What are the options?" | dry description |
| cognition | acquisition (study) | Explanation | "Why…? / Tell me about…" | a discursive article |
Use the terms loosely at first — the point is to force a decision, not to win a
naming argument. Apply the questions at any zoom level: a whole document, a
section, or a single sentence that feels out of place.
Documenting a finished feature usually needs more than one type. A new API
endpoint might want a reference entry (the parameters and return values), a
how-to (accomplishing a real task with it), and maybe an explanation (why it
works the way it does). Don't try to serve all of these in one page. Identify
which types the feature actually needs right now, and write each separately.
Skip the types it doesn't need yet — better a complete how-to than four thin,
half-blurred pages.
When the type genuinely isn't obvious, or you suspect intuition is misleading
you, read references/distinctions.md.
Step 2 — Write to the type's discipline
Once you know the type, open its reference file and follow it. Each gives you
the principles, the sentence-level language patterns, a worked software example,
a skeleton to adapt, and a self-check. Read the one you need — don't work from
the summary below alone.
| Type | One-line discipline | Read |
|---|
| Tutorial | A lesson. Learning-oriented. The user learns by doing, on a single safe path you guarantee works. Ruthlessly minimize explanation. | references/tutorials.md |
| How-to guide | Directions to a real-world goal. Goal-oriented. Assumes competence. Can branch. Omit the unnecessary. Title it "How to …". | references/how-to-guides.md |
| Reference | Neutral technical description. Information-oriented. Austere, consistent, mirrors the structure of the code. Describe and only describe. | references/reference.md |
| Explanation | Discursive discussion. Understanding-oriented. Answers why. Gives context, alternatives, opinions. Read away from the keyboard. | references/explanation.md |
The cardinal rule: don't blur the types
Each type has a natural pull toward its neighbours, and resisting that pull is
most of the craft:
- Writing a tutorial or how-to, you'll feel the urge to explain why. Resist it — give the one-line version and link to an explanation.
- Writing reference, you'll feel the urge to instruct or editorialize. Resist it — link to a how-to or explanation.
- Writing explanation, you'll feel the urge to fold in steps or full specs. Resist it — they live in the how-to and reference.
The fix is almost always the same: say the minimum, then link to the right
place. A one-line "We use HTTPS here because it's more secure (see About
transport security)" keeps a tutorial on track far better than a paragraph.
The two confusions worth knowing cold — because they cause the most damage — are
tutorial vs. how-to (study vs. work) and reference vs. explanation
(consult-while-working vs. read-while-reflecting). Both are covered in
references/distinctions.md.
Write only what's true — the code is the source of truth
Documentation is something users trust and act on, so an invented or stale
detail is worse than a missing one — it sends people confidently toward something
that isn't there. Never document an implementation that doesn't exist.
When your docs describe code — a function, its parameters, return values, flags,
errors, a config key, an endpoint — verify every statement against the actual
code. The code is the only source of truth that can be fully trusted. Specs,
tickets, design docs, the feature description you were handed, and even the
existing documentation can all be out of date or have drifted from reality:
implementations deviate when problems are hit mid-build, and written intentions
are rarely updated to match. So read the real signature, the real schema, the
real behavior in the source. When a description and the code disagree, trust
the code — and flag the discrepancy so a human can reconcile it. If all you
have is a description and you can't see the code, treat the description as an
unverified claim: document what you can ground, and clearly mark what you
couldn't verify rather than presenting it as fact.
This bites hardest in examples, which are tempting to embellish. An example
must demonstrate real, verified behavior — don't reach for an input that
asserts behavior nobody confirmed: how a function handles Unicode or empty input,
what a config does at its limits, a package's install command or name, an error a
call might raise. If a detail matters but you can't verify it against the code,
say so plainly ("behavior for X is unspecified") or leave it out — never paper
over the gap with a plausible-sounding guess. A confident hallucination is the
most damaging thing documentation can contain. Accuracy is the first obligation
of functional quality; see references/quality.md.
Working mode: authoring vs. improving
Authoring new docs for a feature you (or the user) just built:
- Ground yourself in the real implementation first. Read the actual code — the source, signatures, config schema, or API surface you're about to document. The code is the source of truth; don't work from the spec, the ticket, or the feature description alone, since those drift from what was actually built. You cannot write truthful docs for code you haven't looked at, and a plausible guess that turns out wrong is worse than no doc at all (see Write only what's true above).
- List the user needs the feature creates — "learn it," "do task X with it," "look up its options," "understand why it's designed this way." Map each to a type via the compass.
- Write each piece in its proper mode, reading the relevant reference file.
- Match the project's existing docs conventions — file layout, format, tone. Default to Markdown if there's nothing to match. Look at how the repo already documents things before inventing a structure.
- Run the per-type self-check, then the quality pass (references/quality.md).
Improving an existing doc set — don't rewrite it top-down. Diátaxis works
iteratively, and improvements cascade naturally from small changes:
- Choose something — a page, a section, even a single paragraph. Don't hunt for the worst problem; start with what's in front of you.
- Assess it against the standards: What user need does this serve? How well? Does its language and logic match its mode? What's blurred in from another type?
- Decide one change that produces an immediate improvement.
- Do it, and consider it complete. Then repeat.
Resist two temptations when improving: tearing it all down to start over, and
creating empty tutorial/, how-to/, reference/, explanation/ folders to
"fix the structure." Structure should emerge from improved content, not be
imposed on top of it.
Organizing a documentation set
When you're shaping more than a single page — a /docs tree, a landing page, a
whole site — the four types become top-level sections, but the real world is
often more complex (multiple user types, platforms, or topic areas). For how to
structure landing pages, hierarchies, and these two-dimensional cases, read
references/structure.md.
Before you call it done
Read references/quality.md for the self-review pass.
The short version: first secure functional quality (accuracy, completeness,
consistency) — Diátaxis can't give you these but it exposes where they're
missing — then check for deep quality: does each page do exactly one job, in
the right voice, with nothing blurred in from a neighbour, in a way that flows?
Reference files
