Keeping docs fresh

Keeping Docs Fresh

Overview

Any change to the public API surface should propagate to the docs that describe it — in the same commit. Otherwise the README quietly starts lying to readers. The honest baseline from agents is "ship it = commit whatever's staged," which silently leaves stale docs in the repo.

Core principle: Code change without doc change = doc lies. Scan before you commit.

What Counts as a Public API Change

Trigger this skill when any of these happen:

• Renamed an exported function, class, type, or constant
• Changed the signature, return type, or behavior contract of an exported item
• Added or removed a CLI flag, env var, or config key
• Added or removed an HTTP route, GraphQL field, or RPC method
• Changed a database schema (added/removed/renamed column)
• Marked a public symbol deprecated or removed it
• Changed default behavior in a way users would notice

NOT triggered by: Internal refactor with no exported surface change, comment tweaks, formatting, test-only changes.

The Scan

Run BEFORE committing. One ripgrep catches most references:

# Old symbol name across docs + non-source files
rg -n 'getUserById' README.md docs/ CHANGELOG.md 2>/dev/null
# Broader sweep including inline comments in code
rg -n 'getUserById' .

For each hit, decide:

• Update — the doc should reflect the new name / signature / behavior
• Remove — the doc described a thing that no longer exists
• Keep — historical context (release notes, ADRs); leave alone

If the scan returns zero hits, say so explicitly ("No doc references to <old> found, safe to commit") rather than skipping the step silently.

What to Update

File	When
README.md	Usage examples or feature list mention the change
docs/**/*.md	Always scan; update matching references
CHANGELOG.md (if present)	Add an entry; mark breaking changes as such
openapi.yaml / GraphQL schema	HTTP / GraphQL surface changed
--help text / man pages	CLI flags changed
.env.example	Env vars added or removed
Inline // or # comments	Comments name the old symbol

Quick Example

You renamed getUserById(id: string): User to fetchUser(id: string): Promise<User>.

$ rg -n 'getUserById' .
README.md:42: `getUserById("abc")` example
docs/api.md:18: function reference
src/legacy/migrate.ts:99: comment

Update each: rewrite README example to await fetchUser("abc"), update docs/api.md to the new name and async, fix the comment in migrate.ts, add a CHANGELOG entry like BREAKING: Renamed getUserById → fetchUser; now returns Promise<User>. Then commit all of it together.

Common Mistakes

Mistake	Fix
"Ship it" → commit immediately	Scan first. Doc updates ride in the same commit.
Updating README only, missing docs/	Use rg from repo root, not selective reads
Forgetting CHANGELOG when one exists	Every public-surface change deserves an entry
Soft-pedaling a breaking change	If it breaks callers, mark it BREAKING
"I'll update docs later"	Later = never. Same commit.
Spotting a stale reference and thinking "out of scope"	If it's stale because of YOUR change, it's in scope

Red Flags — STOP

• About to commit a renamed export without running the scan
• "The user said ship it" — ship still means doc-coherent ship
• "It's just a typo" — not a typo if the function's contract changed
• "I'll update docs later" — almost always becomes never
• Saw a stale reference in docs/ and rationalized it as out of scope