Salon/docs/documentation.md

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.