Documentation skills
Three real subjects, each documented by five methods from the same brief. Unedited, side by side.
- Before you test BaselineFor Ferdinand (UX): what to prepare, see and do in a user test of the Baseline prototype.
- The receipt featureFor the whole team: what the receipt is, an overview for everyone, then architecture and technical detail for developers.
- Silos: how experiments are kept apartAn architecture and a flow: what an experiment may use, what happens when a change breaks that, and how code is reused by copying.
Requirements
- Show, don’t tell: live pages, diagrams, tables, links, code
- First screen: the thing itself and one line
- Only the words needed
- One fact per paragraph
- Link every page mentioned
- Diagrams wherever there is structure or a sequence
Methods
| No skill | Claude with the brief and requirements only. The yardstick. |
| diataxisJuspay | Diátaxis as a decision procedure: a contract per kind of page and an audit for mixed modes. |
| diataxis-docsPeter Knego | Diátaxis with a rule sheet per kind, a plan, claims checked against the code, C4 diagram rules. |
| technical-writingpstack (Michael Denyer, after Lauren Tan) | Diátaxis, Google style, Simplified Technical English and Global English stacked; unslop removes machine tells. |
| doc-coauthoringAnthropic | Gathers context until it can ask about edge cases, then tests the draft on fresh readers. |
Safety checks and skills turned down: Skills.
Limits
- One run per method, so small differences may be chance.
- Nobody answered questions. Skills built for conversation logged what they assumed instead.
- One diagram type. The runs could only draw boxes and arrows, so every visual became one.
- Claude Opus 5.5 (claude-opus-5-5), 2026-10-13. The runs read the working tree, uncommitted changes included.