writing-docs — Diátaxis documentation authoring

Core principle: a documentation page serves exactly ONE of four distinct reader needs — learning, doing, looking something up, or understanding — and trying to serve two at once makes it worse at both. If you find a document explaining theory in the middle of a set of steps, or a reference page arguing for why a default was chosen, that's not richness, that's quadrant drift, and the fix is to split it, not to smooth it over.

Announce at start: "I'm using the writing-docs skill to author/review this doc."

Canonical source

This skill distills Diátaxis (Daniele Procida) — read the live site for the full treatment; the four-quadrant model, the compass, and the per-quadrant principles below are drawn from it directly, not invented here. When in doubt about an edge case this skill doesn't cover, the canonical source is the tiebreaker.

When to Use

• Whenever you're about to write or substantially restructure a prose documentation page — a tutorial, a how-to guide, a reference page, or an explanation/conceptual page — for a public docs site or any repo documentation meant to be read (not a code comment, not an ADR — ADRs have their own writing-adrs skill and their own format for a different purpose: a permanent decision log, not reader-facing product/project documentation).
• When the sdlc docs pipeline (/sdlc:docs command + knowledge-engineer agent) generates or updates a doc page — in a repo where that pipeline is adopted.
• When reviewing an existing doc and something feels "off" — the compass below is exactly the tool for diagnosing which quadrant a page has drifted out of.

Why Diátaxis

Diátaxis starts from an observation: documentation readers don't have one kind of need, they have four, and each is genuinely different in what it demands of the writing:

• Someone learning a system wants a safe, guided experience with visible results at every step — they need a tutorial.
• Someone already competent, trying to get something done, wants directions to a specific goal — they need a how-to guide.
• Someone working who needs a fact — a parameter's type, a flag's behaviour, a field's default — wants to look it up fast and trust it completely — they need reference.
• Someone trying to understand why something is the way it is wants context, discussion, and connections drawn — they need explanation.

These four needs pull writing in different, often incompatible, directions — a page that's trying to teach AND to be quickly-scannable AND to argue for a design choice is failing all three purposes at once, because good tutorial prose is slow and narrated, good reference prose is austere and fact-only, and good explanation prose is discursive and opinionated — you cannot write in all three registers on the same page and have any of them land well. One document, one quadrant, one register. This is the one-doc-one-quadrant discipline: every page you write should be identifiable, from its first paragraph, as belonging to exactly one of the four.

The Four Quadrants

Tutorial

A lesson, not a demo. The author takes full responsibility for the reader's success: every step must produce a visible, meaningful result, in a fixed, reliable order, with no branching and no optional choices — a tutorial is not the place to offer options. Ruthlessly minimize explanation inline (link out to it instead); explanation offered mid-lesson breaks the reader's flow and teaches the wrong lesson about how to learn. Aim for total reliability: a tutorial that fails partway destroys the confidence it exists to build.

How-to guide

A recipe for someone who already knows the basics and wants a specific, real result. Written from the user's goal, never from the tool's operations ("how to configure X for zero-downtime deploys," not "how to click the deploy button"). Action only — no teaching, no theory, no completeness-for-its-own-sake. It's fine, even expected, for a how-to guide to branch, to skip steps a competent reader doesn't need, and to link out to reference for the full option list rather than enumerating every flag inline.

Reference

Description, and only description, of the machinery: an API, a CLI, a config schema, a set of fields. Austere, neutral, structured to mirror the actual structure of the thing it describes (one entry per symbol/command/field, consistent shape throughout) — a reader consults it, doesn't read it front to back. No narrative, no opinion, no "you should," no "we chose this because" — those belong in explanation or a how-to guide; link to them instead of importing them.

Explanation

Discussion, at a distance from the task at hand — the only quadrant where opinion, alternatives, and "why" belong. Explanation is understanding-oriented: it draws connections, gives context and history, and is honestly allowed to argue a position ("X is better than Y here because …") in a way none of the other three quadrants may. Where a documented architectural decision already exists as an ADR, an explanation page should link to the source ADR(s) under docs/adr/ rather than re-deriving or duplicating the reasoning — the ADR is the durable, single source of truth for why; the explanation page's job is to make that reasoning accessible and readable in context, not to fork it into a second copy that can drift.

The Compass — choosing the right quadrant

When it's unclear which quadrant a piece of content belongs to, ask two questions rather than trusting a first instinct (per Diátaxis's own compass — a genuine decision tool, not a mnemonic):

1. Does this content inform action (doing/practical steps) or cognition (thinking/facts)?
2. Does it serve acquisition (the reader is studying, building a skill) or application (the reader already has the skill and is using it)?

Apply the compass at the level of a whole page when deciding where new content belongs, and at the level of a paragraph or sentence when a page feels like it's drifting — a single sentence of explanation dropped into the middle of a how-to guide's steps is exactly the kind of drift the compass catches that a first read-through can miss.

Anti-Patterns

Every one of these is the same underlying failure — a document doing the job of a different quadrant — expressed four different ways. Catch these before publishing:

Per-Quadrant Structure Templates

Use the quadrant's template as a starting skeleton, not a rigid form — omit a section that genuinely doesn't apply, but don't add sections that belong to a different quadrant.

Tutorial template

---
title: TODO(fill) learning-oriented title, matching the H1 below
description: TODO(fill) one line, used verbatim as the llms.txt description
# related-adrs: repo-root-relative docs/adr/NNNN-*.md paths this page depends on; audit's
# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.
related-adrs: []
---

# [Learning-oriented title, e.g. "Getting started with X"]

[One or two sentences: what the reader will build/achieve, stated plainly — not "in this
tutorial you will learn," just what they'll do. Sets expectations before the first step.]

## Prerequisites

[Concrete, minimal — what must already be true/installed before starting.]

## Step 1: [Concrete first action]

[Instruction in the imperative. Show the exact command/action.]

[The expected, visible result — "You should see…" — so the reader can confirm they're on track.]

## Step 2: [Next concrete action]

...

## What you built

[Brief recap of the end state, so the learner sees what they accomplished. Link onward: to a
how-to guide for the next real task, or to reference/explanation for anything glossed over
along the way.]

How-to guide template

---
title: TODO(fill) specific, real-world goal, matching the H1 below
description: TODO(fill) one line, used verbatim as the llms.txt description
# source: repo-root-relative globs; changes to these files make /sdlc:docs sync draft a refresh of this page. Omit to opt out.
source:
  - TODO(fill) repo-root-relative glob, e.g. plugins/sdlc/commands/loop.md
# related-adrs: repo-root-relative docs/adr/NNNN-*.md paths this page depends on; audit's
# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.
related-adrs: []
---

# How to [specific, real-world goal]

[One sentence naming the problem/goal this guide solves — not what tool it uses.]

## Prerequisites

[What the reader needs already in place/known — assume competence, don't re-teach basics.]

## Steps

1. [Action, in the imperative, addressed to the goal — branch or note alternatives inline only
   where the real-world problem itself branches.]
2. [Next action.]
   ...

[Optional: a troubleshooting/verification note if the real-world task commonly needs one.]

See [reference page] for the full list of options — this guide only covers what's needed to
reach this specific goal.

Reference template

---
title: TODO(fill) exact name of the API/CLI/config surface, matching the H1 below
description: TODO(fill) one line, used verbatim as the llms.txt description
# related-adrs: repo-root-relative docs/adr/NNNN-*.md paths this page depends on; audit's
# ADR-drift flag reads it. Leave [] unless the page genuinely references an accepted ADR.
related-adrs: []
---

# [Exact name of the API/CLI/config surface being described]

[One neutral sentence: what this is, no more.]

## [Symbol/command/field name]

**Type/Signature:** [...]
**Default:** [...] (if applicable)

[Neutral, factual description — what it does, not why you'd want it or when you should use it.]

**Example:**

```[language]
[minimal illustrative usage — illustration only, not a tutorial]
```

## [Next symbol/command/field name]

...

Keep entries structurally identical to each other (same fields, same order) — consistency is what makes reference material fast to scan; a reader shouldn't have to re-learn the shape of each entry.

Explanation template

---
title: TODO(fill) topic, matching the H1 below, e.g. About X or X design
description: TODO(fill) one line, used verbatim as the llms.txt description
# related-adrs: the docs/adr/NNNN-*.md paths this page discusses; audit's ADR-drift flag reads it.
# List the same ADRs the "Related decisions" section links, so the machine key and the prose agree.
related-adrs: []
---

# About [topic] <!-- or: "[Topic] design", "Understanding [topic]" -->

[Open with the "why" question this page answers — explanation exists to answer a real or implied
"can you tell me about…?"]

[Discursive body: context, history, the forces and trade-offs at play, alternatives considered,
and — unlike every other quadrant — reasoned opinion where it's warranted ("X is preferable here
because…"). Draw connections to other parts of the system; this is the one quadrant where doing
so is the whole point.]

## Related decisions

[Where a documented architectural decision underlies this topic, link the source ADR(s) — e.g.
`docs/adr/0007-use-postgresql-as-primary-datastore.md` — rather than restating the ADR's Context/
Alternatives/Consequences here. If no ADR exists for a decision this page discusses, that's fine —
not every explained decision needs a formal ADR — but check `docs/adr/index.md` first if the repo
has one, before writing "why" content that a kept-current ADR might already own. Skip this check
entirely in a repo with no `docs/adr/` directory at all.]

Voice, Craft, and Output Format (parameterized — never hardcode)

This skill is deliberately generic: it says nothing here about what THIS repo's docs should sound like or what markup they should be written in, because that varies per repo and per doc-site platform. Resolve those two things at the START of any drafting or review task, from these sources in order:

1. .claude/project/docs-manifest.md (if it exists) — the sdlc /sdlc:docs pipeline's per-repo manifest of voice guidance and target output format (e.g. Mintlify MDX vs. plain Markdown vs. another doc-site's flavor, front-matter schema, any repo-specific terminology or tone rules). This is the primary source once a repo has adopted the docs pipeline.
2. .claude/project/project-context.md — fall back here for anything the docs-manifest doesn't state (or when no docs-manifest exists yet): detected stack/framework, any existing voice conventions documented for other content (e.g. a marketing/brand voice guide the repo already maintains), and the base branch / PR conventions for where a doc change should land.
3. Neither exists or is silent on a point — default to plain, precise Markdown with no platform-specific extensions, and a neutral, direct technical voice (no unexplained jargon, no marketing language, active voice, second person for reader-facing instructional prose). Don't invent a house style; state plainly what you defaulted to so a human reviewer can correct it.

Regardless of which source resolves voice and format, these craft rules apply universally, because they follow from the quadrant model itself rather than from any one repo's taste:

• Match register to quadrant — tutorial prose is warm, narrated, first-person-plural ("we'll…"); how-to prose is terse and imperative; reference prose is austere and impersonal; explanation prose may be reflective and first-person ("I" or "we" reasoning through a topic) — don't let one page's register bleed into another's.
• Title says what the page is — a reader (and a search engine) should know which quadrant a page belongs to from its title alone: "Getting started with X" reads as a tutorial, "How to configure X" as a how-to guide, "X reference" as reference, "About X" / "X design" as explanation. A vague title ("X") tells the reader nothing about what kind of page they're opening.
• Link across quadrants instead of importing content across them — every quadrant will legitimately want to point at another (a how-to guide linking to reference for the full flag list, a tutorial linking to explanation for the "why," an explanation page linking to the how-to guide with the actual steps) — that's healthy Diátaxis practice, not drift. Drift is when the content itself (not just a link) crosses the boundary.
• No TBDs in published docs — an unfinished doc is worse than no doc; if a fact is genuinely unknown, say what's known and flag the gap explicitly rather than leaving a placeholder.
• No em-dash inside title: or description: frontmatter — /sdlc:docs's llms.txt regen (docs-pipeline-core.md §8) parses each generated entry positionally as title — one-line description — relative link, splitting on a space, an em-dash, and a space. An em-dash inside either field's own value collides with that delimiter and breaks the split. Use a comma, colon, or plain hyphen instead when the title/description itself needs a pause.

Self-Review Checklist (run before publishing/committing)

• The page is identifiable as exactly one quadrant from its title and opening paragraph
• The page carries title + description frontmatter (both filled — no unfilled TODO(fill) sentinel left), and related-adrs: (empty [] unless the page genuinely references an accepted ADR); if this is a how-to/integration-guide page with source: present, its glob(s) are real paths, not the scaffold's TODO(fill) example
• Neither title: nor description: contains an em-dash — it collides with the llms.txt regen's field delimiter
• No anti-pattern from the table above is present anywhere in the page
• The page follows its quadrant's structure template (sections present, none borrowed from another quadrant)
• Cross-quadrant references are links, not inlined/duplicated content
• If this is an explanation page discussing a decision with an existing ADR, it links to that ADR rather than re-deriving its reasoning
• Voice and output format were resolved from docs-manifest → project-context → stated default, in that order — not assumed or hardcoded
• No TBDs — any genuine open gap is stated plainly, not left as a placeholder

Applied to a familiar analogy

Diátaxis's own comparison (cooking) transfers cleanly and is worth keeping in mind when a quadrant call feels ambiguous: a cooking lesson teaches you to cook (tutorial); a recipe gets you a specific dish without teaching you anything (how-to guide); the nutrition label states facts with zero narrative (reference); a book about the history and science of cooking helps you understand cooking more deeply without directly helping you cook tonight's dinner (explanation). None of the four substitutes for another, and mixing them — a recipe that stops to teach knife skills, or a nutrition label with marketing copy — makes the result worse at its actual job.