Documentation

Good documentation preserves decisions, usage, constraints, failure modes, and maintenance guidance for future readers—including you in six months. Types serve different jobs: README for onboarding, ADR for decisions, runbooks for operations, API docs for contracts.

| Doc type | Best for | |----------|----------| | ADR | Why we chose Postgres over Dynamo for billing | | Runbook | How to fail over read replica | | README | Local setup and test commands | | API reference | Request/response contracts |

On interviews: explain what you would document after shipping async export—operational limits, on-call steps, and the rejected sync-only approach.

Common pitfalls: docs only on happy path; stale screenshots; decisions living only in merged PR threads; documenting implementation instead of contracts.

The trade-off is writing time now versus onboarding cost and repeated incidents later.

Checklist:

• Record decision, alternatives, and consequences.
• Document failure modes and alerts.
• Keep setup steps executable.
• Review docs when behavior changes.