Документация

Хорошая documentation сохраняет decisions, usage, constraints, failure modes и maintenance guidance для будущих читателей — включая вас через полгода. Типы для разных задач: README для onboarding, ADR для decisions, runbooks для operations, API docs для contracts.

| Тип doc | Лучше для | |---------|-----------| | ADR | Почему Postgres, а не Dynamo для billing | | Runbook | Failover read replica | | README | Local setup и test commands | | API reference | Request/response contracts |

На интервью: что документируете после async export — operational limits, on-call steps, отвергнутый sync-only подход.

Типовые ошибки: docs только happy path; устаревшие screenshots; decisions только в merged PR; implementation вместо contracts.

Компромисс — время writing сейчас против стоимости onboarding и повторных incidents позже.

Чеклист:

• Decision, alternatives и consequences.
• Failure modes и alerts.
• Setup steps исполняемы.
• Review docs при смене behavior.