Сообщить об ошибкеКороткий ответ
Код показывает, что создано, но не всегда объясняет зачем, кто отвечает и как безопасно действовать при сбое. README должен помогать использовать и менять модуль, а runbook — быстро диагностировать типовую проблему и восстановить сервис.
Как это работает подробнее
Документация снижает зависимость от памяти автора и время реакции on-call. Её полезность проверяется тем, может ли инженер без устных подсказок выполнить изменение или пройти диагностику.
- README модуля. Назначение, ограничения, входы, выходы, зависимости, пример использования и порядок обновления.
- Runbook. Симптомы, метрики и логи, шаги диагностики, безопасные действия, откат и эскалация.
- Владение. Ответственная команда, канал связи и дата последней проверки документа.
Пример кода
README structure
Назначение: очередь уведомлений для production
Входы: queue_name, visibility_timeout
Выходы: queue_arn
Зависимости: AWS provider, KMS key
Проверка: отправить тестовое сообщение и проверить метрику обработки
Откат: вернуть предыдущую версию модуляЧто использовать на практике
- Расположение. Хранить README рядом с кодом, а runbook — в доступном on-call месте со ссылкой из алерта.
- Обновление. Менять документацию в том же PR, где меняются интерфейс, поведение или процедура восстановления.
- Проверка. Периодически проходить runbook на staging или во время game day.
Подводные камни
- Частая ошибка. Описывать только happy path и не фиксировать ограничения, откат и известные симптомы.
- Устаревание. Документ без владельца и проверки быстро становится опаснее отсутствующего, потому что создаёт ложную уверенность.