Documentation Guidelines¶
Documentation is treated as production code in this repository.
Standards¶
- Accurate: reflects current runtime behavior, schema, and workflows.
- Actionable: command snippets run as written.
- Traceable: major decisions link to ADRs and roadmap entries.
- Maintained: stale plans are archived; active plans stay current.
Update Triggers¶
Update docs in the same PR when changing:
- API routes, parameters, response contracts, or error behavior
- database schema, migrations, or bootstrap workflows
- setup steps, scripts, environment variables, or CI workflows
- roadmap/milestone status
Link and Path Rules¶
- Use repository-relative links (for example,
docs/planning/roadmap.md). - Never use absolute local paths or
file://links. - Prefer stable links to source-of-truth docs over duplicate explanations.
Active vs Historical Docs¶
- Active docs should describe current behavior.
- Historical plans should be clearly marked as archived/historical and removed from active task lists.
- The roadmap (
docs/planning/roadmap.md) remains the primary status entry point. - Documentation automation (
scripts/check-docs.sh) validates active docs and intentionally excludes designated historical snapshots.
Required Updates for Major Features¶
- Update roadmap status:
docs/planning/roadmap.md - Update related implementation plan:
docs/planning/implementation/* - Add/update ADR when architecture or contracts changed:
docs/adr/* - Update public docs for externally visible behavior:
README.md,docs/API.md,docs/architecture/*
Documentation Quality Check¶
Run before opening a PR:
This check enforces high-signal documentation hygiene rules used by CI.
The docs platform remains on MkDocs 1.x in the current wave. Do not swap this repo to Zensical or replace the mkdocs gh-deploy publishing path until the shared Wave 3 migration gate is explicitly opened in docs/planning/roadmap.md.
Attribution Policy¶
Only human contributors may be listed as authors/co-authors in documentation and commits.