Diataxis Docs Writer

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:

1. Action or cognition? (Is this about what the user does, or what they know?)
2. Acquisition or application? (Is the user studying, or working?)

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.

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.

---