52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
# Documentation Practices
|
|
|
|
These standards aim to keep documentation reliable as the codebase grows.
|
|
|
|
## Principles
|
|
|
|
- Single source of truth: one canonical doc per topic; link instead of duplicating.
|
|
- Proximity: keep docs close to the code they describe when possible.
|
|
- Freshness: update docs in the same PR as the code change.
|
|
- Observable behavior: describe what someone can see or run to validate the behavior.
|
|
|
|
## Required Docs By Area
|
|
|
|
- Architecture and major decisions: `docs/architecture.md` and `docs/adr/`.
|
|
- Feature delivery plans: `docs/execplans/` (required by `PLANS.md`).
|
|
- Operational procedures: `docs/runbooks/`.
|
|
- Risks and gaps: `docs/risks.md`.
|
|
|
|
## When To Write An ADR
|
|
|
|
Use an ADR for any decision that is cross-cutting or hard to reverse, including:
|
|
|
|
- External providers or payment/auth strategy changes.
|
|
- Async vs synchronous execution decisions.
|
|
- Data model changes that affect multiple apps or services.
|
|
|
|
ADRs live in `docs/adr/` and use the template in `docs/templates/adr.md`.
|
|
|
|
## Runbook Expectations
|
|
|
|
Every production-impacting flow should have a runbook that covers:
|
|
|
|
- Symptoms and impact.
|
|
- Detection and quick checks.
|
|
- Safe remediation steps.
|
|
- Rollback or escalation path.
|
|
|
|
Use the template in `docs/templates/runbook.md`.
|
|
|
|
## Writing Style
|
|
|
|
- Be explicit: include exact commands, paths, and expected output where useful.
|
|
- Keep sections short and focused.
|
|
- Avoid unstated assumptions; if a step needs a specific directory, say so.
|
|
|
|
## Review Checklist
|
|
|
|
- Docs updated or explicitly confirmed unnecessary.
|
|
- New runbook added when operational behavior changes.
|
|
- ADR added for new cross-cutting decisions.
|
|
- `docs/risks.md` updated for meaningful gaps added or closed.
|