Documentation workflow
Keep package context, repository canon, ADRs, and public documentation aligned with every code change.
Documentation maintenance is part of the code change, not a cleanup task after merge. Inspect the real diff, identify the facts it changes, update each owning document and affected projection in the same PR, then prove the result.
Working and proven code is primary evidence. Broken, transitional, disputed, or integration-only behavior must keep an explicit evidence state; it must not be promoted to shipped canon.
Where documentation belongs
Each fact has one primary owner. Other pages may project that fact for a different audience, but they link back to the owner instead of creating a second source of truth.
| Document | Owns |
|---|---|
Workspace README.md | Entry points, installable surface, and commands for that package or app |
Workspace CONTEXT.md | Local responsibilities, seams, invariants, proof, and update triggers |
docs/canon/ | Current cross-package architecture, domain language, and repository contracts |
docs/adr/ | Architectural decisions, alternatives, consequences, and supersession; indexed by docs/canon/adr-index.md |
docs/governance/ | Documentation ownership, routing, evidence vocabulary, and deletion controls |
| Public docs | Tutorials, how-to guides, reference, and explanations for consumers and contributors |
| Historical evidence | Time-bound plans, audits, milestones, and handoffs that must not masquerade as current truth |
Start with the repository
CONTEXT-MAP.md,
then read the nearest workspace README.md and CONTEXT.md. Use the
ownership contract
if two documents appear to own the same fact.
The same-PR loop
- Inspect the real change. Read the diff, callers, consumers, tests, packed exports, and the strongest proof actually run.
- Name every changed fact. Separate interface, behavior, responsibility, architecture, operations, and evidence changes.
- Find the owner. Route each fact through the update map.
- Update projections. Change the package context, canon, ADR, public page, or operation that repeats or depends on that fact.
- State the evidence. Use one exact state from the repository's evidence vocabulary, then link capability status where a public surface has mixed proof strength.
- Handle moved prose. Every deleted or moved document needs a disposition and a surviving owner; deletion alone does not resolve stale truth.
- Verify. Run the owning workspace's targeted proof, documentation gates, and browser QA for public-site changes.
- Leave a receipt. Record the owners updated, evidence boundary, commands, browser routes, and unresolved gaps in the PR.
What a change triggers
| Changed fact | Required documentation impact |
|---|---|
| Public API, export, schema, or result | Package owner and published reference; update tutorials or guides that use it |
| Runtime behavior or failure mode | Owning context, reference errors, and affected how-to or explanation pages |
| Package or application seam | Both affected contexts and the cross-package map or canon |
| Architectural decision | Create or amend an ADR and link every affected context |
| Capability or proof strength | Update capability status everywhere the claim is projected |
| Operator command or deployment behavior | Owning context and operations procedure |
| Deleted or moved prose | Disposition ledger entry and verified surviving owner |
The complete routing matrix lives in
docs/governance/update-map.md.
Choose the public page type
Use the Diátaxis section that matches the reader's job:
- Tutorial: a learning journey with a successful end state.
- How-to: steps for completing one concrete task.
- Reference: exact signatures, inputs, outputs, errors, and capability state.
- Explanation: concepts, boundaries, trade-offs, and why the system works this way.
A single page should have one primary job. Link between page types instead of mixing a tutorial, API catalog, and architectural essay together.
Verify before review
vp run docs:check
vp run docs:buildFor a public-site change, serve the built docs and use computer-use browser QA. Check every changed route at desktop and mobile widths, exercise navigation and links, and inspect the browser console. A successful build proves compilation; it does not prove that the page is readable or the navigation is correct.
PR documentation receipt
Copy this into the PR description or handoff:
### Documentation receipt
- Changed facts:
- Primary owners updated:
- Public or internal projections updated:
- Evidence state and proof:
- Commands run:
- Browser routes and viewports checked:
- Documents moved or deleted, with disposition:
- Unresolved gaps and cleanup issues:After merge, CI repeats the repository gates and the documentation application deploys only through its configured release path. Documentation facts are not deferred until then: the code and its documentation land together.