| id | DEV-330 | ||
|---|---|---|---|
| title | Keep Docs in Sync | ||
| status | active | ||
| enforcement | manual | ||
| severity | error | ||
| depends_on |
|
When a functional change skips the README or a new doc is left unlinked, the documentation no longer matches the code or cannot be found, and readers act on information that is wrong or invisible.
Documentation is only useful while it tracks the code. It falls out of sync when a change updates behavior but not its docs, or when a new doc lands with nothing pointing at it.
- Ship doc updates in the PR that makes them true. A functional change that touches setup steps, environment requirements, or file references leaves the README wrong the moment it merges, and a follow-up PR to fix it often never comes.
- Link a new doc from the index it belongs under, the root
README.mdor a subtree index, per DEV-337, so it is reachable and not orphaned. An unreachable file is invisible, so readers fall back on a stale copy or ask a question the doc already answers.
Each fact must also live in a single canonical place, per DEV-335, so the copy you keep in sync is the only copy.
- Functional changes update the README in the same PR
- New docs are linked from their index and reachable from the root, not orphaned