# Document

> Add documentation where it earns its place, and only there. The hard part of this skill is restraint: most code does not need a comment, and a docstring that restates the signature is worse than none — it rots, and it trains readers to skip comments. Document the *why* and the non-obvious; never the *what* the code already shows.

- Skill: `steph-dove/document` (Agent Skill)
- Install (CLI): `npx skillmds@latest add steph-dove/document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steph-dove/document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: steph-dove (https://skillmd.com/u/steph-dove)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/steph-dove/document

---


Add documentation where it earns its place, and only there. The hard part of this skill is restraint: most code does not need a comment, and a docstring that restates the signature is worse than none — it rots, and it trains readers to skip comments. Document the *why* and the non-obvious; never the *what* the code already shows.

## Phase 1: Decide what actually needs documenting

1. **Read the target** — the file, module, or diff the user named (default to the current change if they named nothing). Read enough of the surrounding code to know what a reader could already infer.
2. **Match the repo's existing doc style.** Read a few already-documented files: docstring convention (Google / NumPy / reST / JSDoc / TSDoc), whether public APIs carry docstrings, how module headers look. Match it exactly — don't introduce a new style.
3. **Select ruthlessly.** Document something only if it clears this bar:
   - **Public API surface** — an exported function/class/module whose contract (params, return, raises, side effects) a caller needs and can't see from the body.
   - **Non-obvious *why*** — a workaround, an invariant, a performance trade-off, an ordering dependency, a link to an issue/spec that explains a surprising choice.
   - **A gotcha** — behavior that would surprise a competent reader (a subtle edge case, a footgun, a "must call X before Y").

   If a candidate doesn't clear the bar, **leave it undocumented** — that is the correct outcome, not a gap. Say plainly which things you deliberately left alone and why.

## Phase 2: Write it

1. **Comments/docstrings: explain intent, not mechanics.** A single line is usually enough. Never narrate steps ("loop over the items"), restate the signature, or echo a name. If the clearest fix is a better name instead of a comment, suggest that.
2. **Docstrings: state the contract concisely** — what it does, its params/return, and what it raises or mutates — in the repo's format. Skip the obvious; a one-line summary is fine when that's all the contract is.
3. **README / guide prose:** lead with what the reader needs to do or know; keep examples runnable and current; don't duplicate what's already documented elsewhere — link instead.
4. **Don't change code behavior.** This skill writes documentation. If documenting reveals a bug or a confusing API, report it (for the debug or refactor skill) rather than fixing it here.

## Phase 3: Verify

- **Re-read each doc against the code it describes** — an inaccurate comment is worse than none. Confirm params, return types, and described behavior actually match.
- If the repo builds docs (e.g. Sphinx, TypeDoc, mkdocs — check CLAUDE.md), build them to confirm nothing is malformed.

{{HUMANIZE}}

## Rules

- **Bias toward less.** When unsure whether something needs a comment, it doesn't. Under-documenting is a smaller sin than comment noise.
- One-line comments by default; reserve multi-line docstrings for genuine public-API contracts.
- Never add changelog/narration comments ("Added to fix…", "Now we handle…") or comments that restate the code.
- Don't document code you didn't read fully — a plausible-but-wrong doc is a trap for the next reader.
- Keep docs next to the code they describe; don't spawn a separate doc file when a docstring would do.

## When NOT to use

- The user wants code written or changed — that's implement/refactor; this skill only writes docs.
- The user wants a PR description or release notes — use the pr or release skill.
- The code is self-explanatory and the user just feels it "should have comments" — say so; adding noise to clear code makes it harder to read, not easier.