Document every shipped surface

If it ships, it has a doc page. No exceptions, no "we'll document it later."

What counts as a surface, for a CLI-shaped product:

• Every command and subcommand
• Every flag of every command
• Every config key, with default, type, and what it controls
• Every IPC request and response variant
• Every search operator (every is:, has:, every field)
• Every keybinding

For an app: every settings panel, every notification type, every keyboard shortcut, every URL scheme, every webhook event.

The discipline only holds if it's mechanical

A policy that depends on remembering to update docs decays. The only version that survives contact with reality is the one CI enforces. In mxr, clap --help snapshots are captured in tests, the CLI reference is regenerated from them, and the build fails on snapshot drift. Adding a flag without re-snapshotting breaks the build — that's the point.

See Generated Docs as Drift Defense for the mechanism.

Source of truth maps to doc page

Every surface has one source of truth and one doc page. When they're far apart, drift creeps in.

Hand-written pages are weaker than generated ones. For anything regenerable, generate it.

What this catches

Without this discipline, a flag ships and is documented six weeks later when a user files a bug. The user has already lost trust. The fix is mechanical: every flag has a generated page, every config key has a row in the reference table, every search operator has an entry. The author can't get the PR through without it.

See also

• Generated Docs as Drift Defense — the CI mechanism that makes this enforceable
• How I Write Software Docs — the full synthesis
• Mxr — the project where this discipline lives