Skip to main content

Docs with build

What makes "working software with docs and tests" real rather than aspirational: docs are produced or updated in the same PR as the code, reviewed in that PR, and a stale-docs check fails the merge gate if they drift.

What agents must produce or update, per change​

Organised by Diátaxis type — the four kinds of documentation, so agents know which they're writing:

  • Reference — generated from code where possible (APIs, config, schema); hand-maintained only where generation can't reach.
  • How-to / runbook entries — operational steps for anything the change adds to how the service is run or diagnosed.
  • Explanation / ADR — architecture and decision deltas (see Decision records).
  • Tutorial — only when a change introduces a new capability a user or developer needs walking through.

Rules​

  • Same PR. Docs land with the code that changes them — never a follow-up ticket that never happens.
  • In-repo. Documentation lives in the repository, versioned and diffable, not in a wiki that drifts out of sync (knowledge silos are on the problem list RAPID exists to fix).
  • Stale-docs check. CI flags code changes to documented surfaces whose docs didn't move; the gate blocks until they're reconciled.
  • Written for humans and agents. The same docs are a human's reference and an agent's loaded context — see Repo context & memory.

Docs are one of the compounding artefacts: created in Build, kept alive forever in Flow-state.