Keeping the docs current
Where things live
Section titled “Where things live”| Content | Location | Nature |
|---|---|---|
| Product, domain, architecture, decisions, operations | this site (docs/) |
Living. Updated in the same pull request as the change it describes |
| Stage plans and per-ticket completion reports | improvement-plans/ |
Historical evidence. Written once, corrected only for factual errors |
| What exists now | Product → Features | Living: one row per area, updated when an area changes |
| What changed and when | Changelog | Append-only by day: one line per merged pull request, newest first |
| Status snapshot | PROJECT_STATE.md |
Refreshed at stage boundaries |
| Setup and commands | README.md |
Living, kept short; the Local setup page mirrors it |
| Conventions for contributors and coding agents | CLAUDE.md |
Living |
The rule
Section titled “The rule”A pull request that changes behaviour described on this site changes the page in the same pull request. A pull request that makes a decision adds or amends a decision record. Every pull request adds its line to the changelog under the day it merges. One that adds or changes a feature also updates its row in the feature list. Reviewers treat a missing doc change like a missing test.
The changelog line says what changed for shops in plain words, then the pull request number: “Team: owners invite staff by email… (#70)”. Platform and operations changes go under Platform, and fixes under Fixes.
Shipping a major feature
Section titled “Shipping a major feature”A pull request that adds or substantially changes a feature completes this list before it is opened. CLAUDE.md carries the same list for coding agents.
- Changelog: its line under today’s date (changelog).
- Feature list: the area’s row says what now exists (features), and the core flows if the flow changed.
- Roadmap: a dated paragraph if a user or investor would notice it.
PROJECT_STATE.md: the feature row and the recommended next steps.- The feature’s own page: domain, architecture or operations. Add an ADR when it settles a policy, and update the architecture overview for new routes, tables, integrations or scheduled jobs.
- Landing page: if the feature changes what the landing page may claim, or closes one of its open items, update its copy in both languages and any screenshot of a screen that changed.
- Strings and tests: both languages, with
lang:checkclean, and tests for rules, permissions and tenant boundaries. - Shipping: the local check and stamp, the merge, and a confirmed deploy.
Writing decision records
Section titled “Writing decision records”One file per decision under docs/src/content/docs/decisions/, numbered in order. Four parts: status with date, context, decision, consequences. Amend a record when the decision changes; do not delete it. Link to it from the page whose rule it explains.
Diagrams
Section titled “Diagrams”Mermaid blocks render on this site. Prefer a diagram only when it shows a mechanism a table cannot: state machines, request flows, entity relationships.
Building
Section titled “Building”The site is a Starlight project in docs/ with its own package.json. It builds into public/docs and is served by the application at /docs/. CI builds it on every pull request so a broken link or frontmatter error fails the build. Write absolute links with the /docs/ prefix.