| name | write-documentation |
| description | Write software documentation structured by Diátaxis. Use when the user wants a tutorial, how-to guide, reference page, explanation doc, or user guide — "write docs", "document this", "we need a guide for X". Not for READMEs (write-readme) or docstrings (update-docstrings). |
Write Documentation (Diátaxis)
Produce one document per run, typed by the Diátaxis quadrant it serves: a tutorial (a lesson), a how-to guide (a recipe), reference (a dictionary), or an explanation (a discussion).
Workflow
-
Classify. Place the request on the Diátaxis compass:
- Does the document serve the reader's action (they are doing something) or cognition (they are understanding something)?
- Does it serve acquisition (they are studying) or application (they are working)?
| acquisition (study) | application (work) |
|---|
| action | tutorial | how-to guide |
| cognition | explanation | reference |
A request that spans quadrants is more than one document — say so and pick the primary one for this run.
-
Confirm the brief. State your classification and ask about whatever is still unknown of:
- Audience — who reads this, and what do they already know?
- Reader's goal — what can they do or understand after reading?
- Scope — what is in, and what is explicitly out?
Done when document type, audience, goal, and scope are each either answered by the user or proposed by you and accepted.
-
Load the quadrant's rules. Read the matching file before outlining:
-
Propose an outline. A table of contents, one line per section, shaped by the quadrant's rules. Await approval before writing.
-
Write. Done when every section of the approved outline is fully written — none stubbed, summarized, or deferred.
Sources
Work only from material the user provides and the codebase at hand. Provided markdown files calibrate tone and terminology; quote them only on request. Verify every code snippet against the actual code before including it.
