Purpose
Produce a complete, navigable documentation set partitioned by the Diataxis framework: every document serves exactly one of four reader needs, and the set as a whole covers the public surface. The failure this prevents is the all-too-common documentation blob that tries to teach, instruct, specify, and explain in one undifferentiated wall, serving none of those needs well. Read the code before writing a line; documentation written from the README and guesses describes a system that does not exist.
The four Diataxis modes
Every documentation page serves one reader in one mode. Mixing modes in a single page is the central anti-pattern; a tutorial that stops to explain design rationale loses the learner, and a reference that pauses to teach loses the lookup.
| Mode |
Reader's question |
Orientation |
The page is |
Voice |
| Tutorial |
"Teach me, I'm new here" |
Learning |
A lesson with a guaranteed working result |
"We will build..." hands-on, no detours |
| How-to guide |
"How do I accomplish X?" |
Task |
A recipe for a goal the reader already has |
"To do X: step, step, step" |
| Reference |
"What exactly is Y?" |
Information |
A complete, dry, authoritative description |
"Z accepts these params, returns this" |
| Explanation |
"Why is it this way?" |
Understanding |
A discussion of context, tradeoffs, alternatives |
"This was chosen because..." |
The two axes that disambiguate them: tutorials and how-tos are action (the reader is doing); reference and explanation are cognition (the reader is studying). Tutorials and explanation serve study/acquisition; how-tos and reference serve work/application. When unsure which mode a page is, name the reader's question out loud; it lands in exactly one cell.
Workflow
Copy this checklist and track progress:
Docs Progress:
- [ ] 1. Codebase archaeology
- [ ] 2. Partition: decide which modes each subject needs
- [ ] 3. Draft each page in its single mode
- [ ] 4. Cross-link the modes
- [ ] 5. Quality gates
1. Codebase archaeology
Read the actual public surface before writing: entry points, exported functions and types, CLI commands and flags, API routes, config options, the existing README and any docs. List the complete public surface; this list is the coverage contract for the Reference pages and the menu of candidate How-to goals. Documenting from memory or the existing README guarantees describing half the feature and inventing the other half.
2. Partition: decide which modes each subject needs
Not every subject needs all four modes; forcing four pages per thing is how doc sets bloat. Decide per subject:
| Subject |
Usually needs |
| A whole product or library (new user) |
Tutorial (one, the getting-started path) + Reference + a How-to per common task |
| A public API surface, CLI, config schema |
Reference (complete, mandatory) + How-to per real task |
| An internal module or subsystem |
Reference + Explanation (the why); rarely a tutorial |
| A non-obvious design decision or model |
Explanation (and link it from the ADR if a decision record exists) |
Rules: one Tutorial is usually enough for a whole product (the single path that gets a newcomer to a working result); add a How-to only for a task a real user actually performs, not every API method; Reference must cover the full surface from step 1.
3. Draft each page in its single mode
Hold each page to its mode's contract:
- Tutorial: a concrete, runnable, start-to-finish path that produces a visible result, fast (aim for the first working result within roughly three steps). Every command runs as written. No "you could also", no rationale detours, no error-handling lectures; a learner needs momentum and a win, not completeness. Teaching craft within the lesson is
teach-through-writing's job.
- How-to: title starts with "How to"; assumes the basics; solves one stated goal; ends when the goal is met. Real-world messy goals ("How to deploy behind a corporate proxy"), not feature tours.
- Reference: complete and austere. Every public item: signature, parameters with types and defaults, return shape, errors, one minimal example. Pull facts directly from the code, never from memory. Dry is correct here; reference is consulted, not read.
- Explanation: the why. Context, the alternatives considered and rejected, the tradeoffs, the boundaries of the design. This is the only mode where opinion and discussion belong.
4. Cross-link the modes
The set works because the modes connect: each Reference entry links to the How-to that uses it; each How-to links to the Reference for its objects; the Tutorial links onward to both for "where next"; Explanation links to the Reference it contextualizes. A reader in the wrong mode for their need should be one click from the right one. Provide an index (README or docs landing) that routes by reader intent: new here / how do I / what is / why.
5. Quality gates
Before declaring the set done:
Gotchas
- Mode-mixing is the disease Diataxis cures; do not reintroduce it. The instinct to "be helpful" by adding a why-paragraph to a tutorial or a worked lesson to a reference is exactly the instinct that produced the unusable blob. Put the why in Explanation and link it.
- Reference is generated from the code, not the docs. The single most common doc defect is a reference that drifted from the implementation. Read signatures and defaults from source every time; a confidently wrong default is worse than a missing one.
- One tutorial, not one per feature. Tutorials are expensive to maintain (every step must keep working) and a newcomer needs one reliable path, not twelve. Breadth lives in How-to and Reference; the Tutorial is the single front door.
- A How-to per API method is reference cosplay. If the "guide" is just one method with its params, it belongs in Reference. How-to earns its page only when it composes several steps toward a goal the reader brought with them.
- Documentation that lies is worse than none. A reader trusts docs and stops reading code; a stale example sends them down a path that no longer exists. The "examples run as written" gate is not optional polish, it is the credibility of the whole set.
1---2name: write-docs3description: This skill should be used when generating or organizing a documentation set for a codebase, library, CLI, or API: writing a README and docs from scratch, filling documentation gaps, or restructuring docs that have become a confusing pile. It applies when the user says "document this", "write the docs", "the docs are a mess", "add docs for this feature", or "what docs does this need". It should not be used for the prose craft of a single explainer or tutorial (use teach-through-writing), for recording one architectural decision (use spec), or for API contract definition (use spec).4---56## Purpose78Produce a complete, navigable documentation set partitioned by the Diataxis framework: every document serves exactly one of four reader needs, and the set as a whole covers the public surface. The failure this prevents is the all-too-common documentation blob that tries to teach, instruct, specify, and explain in one undifferentiated wall, serving none of those needs well. Read the code before writing a line; documentation written from the README and guesses describes a system that does not exist.910## The four Diataxis modes1112Every documentation page serves one reader in one mode. Mixing modes in a single page is the central anti-pattern; a tutorial that stops to explain design rationale loses the learner, and a reference that pauses to teach loses the lookup.1314| Mode | Reader's question | Orientation | The page is | Voice |15|---|---|---|---|---|16| Tutorial | "Teach me, I'm new here" | Learning | A lesson with a guaranteed working result | "We will build..." hands-on, no detours |17| How-to guide | "How do I accomplish X?" | Task | A recipe for a goal the reader already has | "To do X: step, step, step" |18| Reference | "What exactly is Y?" | Information | A complete, dry, authoritative description | "Z accepts these params, returns this" |19| Explanation | "Why is it this way?" | Understanding | A discussion of context, tradeoffs, alternatives | "This was chosen because..." |2021The two axes that disambiguate them: tutorials and how-tos are *action* (the reader is doing); reference and explanation are *cognition* (the reader is studying). Tutorials and explanation serve *study/acquisition*; how-tos and reference serve *work/application*. When unsure which mode a page is, name the reader's question out loud; it lands in exactly one cell.2223## Workflow2425Copy this checklist and track progress:2627```text28Docs Progress:29- [ ] 1. Codebase archaeology30- [ ] 2. Partition: decide which modes each subject needs31- [ ] 3. Draft each page in its single mode32- [ ] 4. Cross-link the modes33- [ ] 5. Quality gates34```3536### 1. Codebase archaeology3738Read the actual public surface before writing: entry points, exported functions and types, CLI commands and flags, API routes, config options, the existing README and any docs. List the complete public surface; this list is the coverage contract for the Reference pages and the menu of candidate How-to goals. Documenting from memory or the existing README guarantees describing half the feature and inventing the other half.3940### 2. Partition: decide which modes each subject needs4142Not every subject needs all four modes; forcing four pages per thing is how doc sets bloat. Decide per subject:4344| Subject | Usually needs |45|---|---|46| A whole product or library (new user) | Tutorial (one, the getting-started path) + Reference + a How-to per common task |47| A public API surface, CLI, config schema | Reference (complete, mandatory) + How-to per real task |48| An internal module or subsystem | Reference + Explanation (the why); rarely a tutorial |49| A non-obvious design decision or model | Explanation (and link it from the ADR if a decision record exists) |5051Rules: one Tutorial is usually enough for a whole product (the single path that gets a newcomer to a working result); add a How-to only for a task a real user actually performs, not every API method; Reference must cover the full surface from step 1.5253### 3. Draft each page in its single mode5455Hold each page to its mode's contract:5657- **Tutorial**: a concrete, runnable, start-to-finish path that produces a visible result, fast (aim for the first working result within roughly three steps). Every command runs as written. No "you could also", no rationale detours, no error-handling lectures; a learner needs momentum and a win, not completeness. Teaching craft within the lesson is `teach-through-writing`'s job.58- **How-to**: title starts with "How to"; assumes the basics; solves one stated goal; ends when the goal is met. Real-world messy goals ("How to deploy behind a corporate proxy"), not feature tours.59- **Reference**: complete and austere. Every public item: signature, parameters with types and defaults, return shape, errors, one minimal example. Pull facts directly from the code, never from memory. Dry is correct here; reference is consulted, not read.60- **Explanation**: the why. Context, the alternatives considered and rejected, the tradeoffs, the boundaries of the design. This is the only mode where opinion and discussion belong.6162### 4. Cross-link the modes6364The set works because the modes connect: each Reference entry links to the How-to that uses it; each How-to links to the Reference for its objects; the Tutorial links onward to both for "where next"; Explanation links to the Reference it contextualizes. A reader in the wrong mode for their need should be one click from the right one. Provide an index (README or docs landing) that routes by reader intent: new here / how do I / what is / why.6566### 5. Quality gates6768Before declaring the set done:6970- [ ] Every public item from step 1 appears in Reference (the coverage contract holds)71- [ ] Every code example and tutorial command actually runs as written, against the current code72- [ ] No page mixes modes (no rationale in the tutorial, no teaching in the reference)73- [ ] Every How-to solves a goal a real user has, and its title names that goal74- [ ] The cross-links resolve and the index routes by intent75- [ ] Names (functions, commands, types) match the code and each other across all pages7677## Gotchas7879- **Mode-mixing is the disease Diataxis cures; do not reintroduce it.** The instinct to "be helpful" by adding a why-paragraph to a tutorial or a worked lesson to a reference is exactly the instinct that produced the unusable blob. Put the why in Explanation and link it.80- **Reference is generated from the code, not the docs.** The single most common doc defect is a reference that drifted from the implementation. Read signatures and defaults from source every time; a confidently wrong default is worse than a missing one.81- **One tutorial, not one per feature.** Tutorials are expensive to maintain (every step must keep working) and a newcomer needs one reliable path, not twelve. Breadth lives in How-to and Reference; the Tutorial is the single front door.82- **A How-to per API method is reference cosplay.** If the "guide" is just one method with its params, it belongs in Reference. How-to earns its page only when it composes several steps toward a goal the reader brought with them.83- **Documentation that lies is worse than none.** A reader trusts docs and stops reading code; a stale example sends them down a path that no longer exists. The "examples run as written" gate is not optional polish, it is the credibility of the whole set.
brandonburrus