# 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.