Документация, которую читают

На приёмке проектов мы регулярно видим эксплуатационную документацию на восемьдесят страниц. Она красивая, полная и абсолютно бесполезная: в аварию по ней не работает никто, потому что искать в ней дольше, чем чинить.

Наш минимальный шаблон

За годы практики мы пришли к формату из трёх артефактов:

• Одна схема. Вся инфраструктура на одном листе. Если не помещается — упрощайте схему, а не добавляйте страниц.
• Одна таблица. Сервисы: где живут, кто владелец, как проверить, как перезапустить, куда звонить. Шесть колонок, никакой прозы.
• Один сценарий. «Всё сломалось в три часа ночи»: пошагово, с командами, по которым дежурный восстановит сервис, не понимая его устройства.

Проверка

Документация считается готовой не после подписания, а после учений: мы просим дежурного инженера заказчика поднять сервис по сценарию, сами наблюдаем и дописываем то, что вызвало вопросы. Обычно хватает одного прогона.

Объём не является доблестью. Доблесть — когда в три часа ночи документ читается за четыре минуты.