Skip to main content

Documentation maintenance

The bible is only valuable if it's accurate. Accurate documentation requires effort to maintain. This page is the discipline.

Drafted from planning · v0.1

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 codeBible update
New migrationUpdate domain/entities/{table}.md
Endpoint addedUpdate relevant slice page; eventually reference/api
Endpoint signature changedUpdate slice page; bump version note if breaking
Lifecycle alteredUpdate domain/lifecycles/{name}.mdx
Cross-cutting decisionWrite a new ADR
Principle redefinedUpdate the principle's page; mark prior interpretation deprecated
New shop onboardedUpdate current-state.md if relevant
Architecture refactorUpdate C4 diagrams + relevant arch docs

The PR-pairing convention​

For changes that span code + bible:

  • One PR per repo (kvick-bike 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​

  1. Fix it in a PR
  2. If the wrong info caused an incident, mention in the post-mortem
  3. 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)

See also​