doc-maintenance

Topics in the source

• Doc Maintenance
• When to use
• When not to use
• The pass
• Style baseline
• Drift detection
• Release-note rules
• Anti-patterns

Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes". A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions. A user-reported bug traced back to outdated documentation. A release is being cut and the docs need a pass against the merged commits. A new feature shipped but only the engineer's PR description describes how to use it. The change is internal-only (private helper rename, refactor) with no user-visible impact. You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first. 1. Establish the baseline. Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR). 2. Enumerate user-visible changes. Read commits and PR descriptions. List, for each change, what a user can now do differently. 3. Map changes to docs. For each change, find ev

This is an excerpt. Refer to the complete source and its current requirements.