Documentation maintenance
The bible is only valuable if it's accurate. Accurate documentation requires effort to maintain. This page is the discipline.
The principle
A wrong doc is worse than a missing doc. Missing forces you to read the code; wrong actively misleads.
What triggers a bible update
| Change in code | Bible update |
|---|---|
| New migration | Update domain/entities/{table}.md |
| Endpoint added | Update relevant slice page; eventually reference/api |
| Endpoint signature changed | Update slice page; bump version note if breaking |
| Lifecycle altered | Update domain/lifecycles/{name}.mdx |
| Cross-cutting decision | Write a new ADR |
| Principle redefined | Update the principle's page; mark prior interpretation deprecated |
| New shop onboarded | Update current-state.md if relevant |
| Architecture refactor | Update C4 diagrams + relevant arch docs |
The PR-pairing convention
For changes that span code + bible:
- One PR per repo (Helm code + bible repo), referencing each other
- Merge order: code first (so users hitting issues find the latest behavior), bible second (so the bible reflects what's live)
For code-only changes that don't need bible updates: fine to merge alone.
For bible-only changes: fine standalone (typo fixes, clarifications, new ADRs).
The "is this still accurate" cadence
- Per slice ship: review the slice's pages, plus glossary, plus any entity touched
- Per ADR: review the principles that the ADR builds on (rare drift; check anyway)
- Per quarterly: read the overview section + current-state.md cold; update what's stale
- Per onboarded shop: review onboarding-a-shop.md against the actual process
Stale-doc detection
Stub: a CI script that flags pages older than 90 days for review. Not built yet; manual cadence above for now.
Voice and style
Reuse the conventions in update the bible. Short, active, examples-first, always cross-link.
What to do when the bible is wrong
- Fix it in a PR
- If the wrong info caused an incident, mention in the post-mortem
- If the wrong info is widespread (multiple pages), do a sweep PR
Don't quietly fix and pretend it was always right — the wrong version is in git history forever; the PR explains why.
Documenting the undone
Slice pages and runbooks include "what's not built" sections. These are honest about gaps. Update them as items move from "not built" to "built."
The risk: a long "not built" list is a fire-and-forget place where TODOs go to die. Counter the risk by:
- Reviewing each slice's "not built" list when working on adjacent slices
- Promoting items to actual GitHub issues when they're ready to be worked on
- Deleting items that we've decided not to do (with a note in the slice page)
Documenting deprecations
When an ADR is superseded:
- The old ADR gets
Status: Superseded by ADR-NNNN - The new ADR links back:
Supersedes: ADR-NNNN - Both remain in the bible; deletion erases history
When a principle is re-interpreted:
- The principle page is updated
- An ADR documents the re-interpretation if it was a deliberate choice
When a feature is removed:
- The slice page is updated with "Removed in YYYY-MM" note
- The relevant entity / lifecycle pages note the removal
- The endpoint reference is removed (or marked deprecated for a grace period)