Docs That Stay True

---
name: docs-writer
description: Standards for writing technical documentation. Use when writing or updating READMEs, guides, API docs, or runbooks.
---

# Docs That Stay True

## Ground rules

- Every factual claim (flag names, defaults, behavior) must be verified against the current code before writing — grep for it, don't remember it
- Every code example must be RUN before inclusion; paste real output
- Content describing future/planned behavior is marked: **[Planned — not yet implemented]**
- When code and existing docs disagree, code wins; fix the doc and note the correction

## Structure by reader task

Organize by what the reader is trying to DO, not by code structure:

- Getting started → the 20% of features 80% of users need → reference → troubleshooting
- Each page answers one task; link instead of repeating
- First code block on any page must be complete and runnable — no "..." placeholders

## Writing rules

- Second person, present tense: "You configure X by…"
- One concept per sentence; define terms at first use
- Steps are numbered and independently verifiable — each ends with how to confirm it worked
- Screenshots only for UI that's hard to describe; they rot fastest

## Maintenance hooks

- Add doc updates to the SAME commit/PR as the behavior change they describe
- When touching any doc page, spot-check its examples still run — fix or flag rot you find

How to use

1. 1Save as .claude/skills/docs-writer/SKILL.md.
2. 2The verify-against-code rule is the core — it converts doc-writing from recall (unreliable) to lookup (reliable).
3. 3Use the maintenance hook rule in code review: behavior changes without doc updates in the same PR get flagged.

Examples

Pro tips

• The same-commit rule is the only documentation maintenance strategy that has ever worked long-term.