Как поддерживать документацию инфраструктуры актуальной: ритуал раз в месяц

MAATRIX

Документацию пишут один раз — в первую неделю после настройки сервера, когда всё ещё свежо в памяти и хочется зафиксировать, «как это работает». Потом происходит десяток мелких правок конфига, три инцидента, смена версии PostgreSQL и один уволившийся сотрудник, который единственный помнил, зачем nginx слушает на нестандартном порту. Документ остаётся лежать на месте, но перестаёт быть картой местности — он описывает систему, какой она была полгода назад. Хуже, что устаревшая документация не нейтральна: она не просто бесполезна, она активно вводит в заблуждение того, кто ей доверился в момент инцидента. Ниже — рабочий ритуал, который держит документацию в соответствии с реальностью без превращения этого в отдельный проект.

Почему документация устаревает быстрее, чем кажется

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

Есть и вторая причина, менее очевидная: у каждого отдельного расхождения документации с реальностью цена кажется нулевой. Подняли порт с 2222 на 2223 и забыли поправить docs/access.md — ничего не сломалось, все и так знают правильный порт. Но такие расхождения не сбрасываются каждый день до нуля, они накапливаются. Через год документ может быть верным на 60%, и хуже всего то, что никто заранее не знает, какие именно 40% — это неверно. В этот момент документ теряет главное свойство, ради которого его вообще заводили: доверие. Мы разбирали похожий парадокс с другой стороны — когда автоматизацию по ошибке принимают за документацию — в статье антипаттерн: скрипт вместо документации: код фиксирует «что», но не «почему» и не гарантирует актуальность сам по себе, потому что playbook тоже правят в спешке.

Третья причина — документация обычно живёт отдельно от кода и конфигов, физически в другом месте (wiki, Notion, отдельный репозиторий). Расстояние между местом изменения и местом фиксации этого изменения прямо пропорционально вероятности, что фиксация не произойдёт.

Ежемесячный ритуал сверки: что проверять и сколько это занимает

Смысл ежемесячной сверки не в том, чтобы переписать документацию заново, а в том, чтобы построчно пройти по ключевым разделам и задать один вопрос к каждому: соответствует ли это реальному состоянию системы прямо сейчас. Разумный бюджет — час-полтора на инфраструктуру из нескольких серверов, если документация уже ведётся; если запускаете ритуал впервые на заброшенном документе, первый проход займёт кратно дольше.

Схема инфраструктуры и список сервисов (15-20 минут). Сверьте документ с реальным списком запущенного:

# Что реально слушает порты на сервере
ss -tlnp

# Какие systemd-юниты активны и когда последний раз менялись
systemctl list-units --type=service --state=running
systemctl show myapp.service -p ExecStart

# Список контейнеров, если инфраструктура на Docker
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Ports}}"

Сравните вывод со схемой в документации построчно. Типичные находки: сервис, который в документе значится как «временный, снести после релиза», а по факту работает уже восемь месяцев; порт, который в схеме один, а в конфиге — другой, потому что кто-то поменял его при разборе конфликта портов и забыл вернуться к документу.

Cron-задачи и systemd-таймеры (10 минут). Реальный список против описанного:

crontab -l
systemctl list-timers --all

Здесь особенно часто расходится реальность: задачу добавили при разборе инцидента как временный костыль, она прижилась, а в документации её нет вообще — или наоборот, задача из документа давно удалена, но запись осталась.

Домены, DNS-записи и сертификаты (10 минут). Пройдитесь по таблице доменов из документации и сверьте с панелью DNS-провайдера и выводом certbot certificates. Поддомены тестовых контуров, которые «пока оставим», живут в документации годами уже после того, как реальный DNS-записи удалили или, наоборот, забыли удалить.

Список доступов (15-20 минут). Самый чувствительный раздел с точки зрения безопасности и один из самых быстро устаревающих — люди приходят и уходят чаще, чем меняется архитектура. Сверьте таблицу «кто/роль/доступ» с реальным списком:

# Ключи, которые реально дают доступ
cat ~/.ssh/authorized_keys | wc -l
awk '{print $NF}' ~/.ssh/authorized_keys

# Пользователи с sudo
getent group sudo

Если находите ключ или пользователя, которого нет в документации — это не мелочь, а сигнал, что доступ выдавался в обход процесса. Подробный разбор именно этой процедуры — в статье ключ подрядчика в authorized_keys: аудит за час, а более широкий взгляд на то, что делать с людьми, которые ушли, но доступ остался — в сотрудник уволился, а доступ остался: аудит за вечер.

Версии ключевого ПО (5-10 минут). Не ради полноты, а потому что версии часто фигурируют в объяснениях других решений документа — «обходим баг из версии 14, при апгрейде до 16 можно убрать костыль». Если версия давно другая, а комментарий остался, это уже не документация, а дезинформация с уверенным тоном.

nginx -v; psql --version; docker --version; node --version

Раздел «почему», а не только «что» (оставшееся время). Это самая трудная для автоматизации часть ритуала — пробежаться по всем комментариям-обоснованиям в документе («настроено так, потому что...») и спросить себя: это обоснование всё ещё в силе? Ограничение, введённое из-за бага в конкретной версии библиотеки, могло стать не нужным после апдейта. Workaround, который был временным решением инцидента полугодовой давности, мог давно превратиться в постоянную часть архитектуры без соответствующей записи.

Полный список того, что вообще стоит фиксировать в документации сервера — со структурой по разделам — разобран в статье документация сервера: что нужно вести; ежемесячный ритуал сверки идёт по тем же разделам, только не «с нуля», а «сверить и поправить».

Обновление документации как часть изменения, а не отдельная задача

Ежемесячная сверка ловит то, что накопилось, но правильная цель — свести объём таких находок к минимуму. Для этого нужна не сила воли, а изменение самой единицы работы: обновление документации должно быть частью того же коммита/тикета/действия, что и само изменение, а не отдельным пунктом «занесу в документацию потом».

Практически это значит несколько конкретных привычек:

• Определение готовности задачи включает документацию. Если у вас есть чек-лист «что значит done» для инфраструктурных изменений — добавьте туда пункт «документация обновлена» на равных с «изменение протестировано». Задача не закрывается, пока пункт не отмечен, точно так же, как она не закрывается без тестирования.
• Документация — часть того же pull request/коммита, что и конфиг. Если /etc живёт под git через etckeeper или конфигурация инфраструктуры описана в Ansible/Terraform, держите markdown-файл документации в том же репозитории, в соседней папке docs/. Ревьюер, который смотрит diff конфига, видит рядом diff документации — расхождение бросается в глаза сразу, а не через месяц.
• Правило одной строки сразу, а не абзаца потом. Полноценное описание изменения — с контекстом, альтернативами, которые рассматривали и отвергли — можно дописать позже. Но одна строка факта («2026-08-14: порт SSH сменён с 22 на 2222, старый закрыт firewall») должна попадать в документ в момент изменения, максимум в тот же день. Later почти всегда означает never.
• Инцидент закрывается записью в документации, а не только фиксом. Если инцидент вскрыл, что документация врала (порт не тот, зависимость не та, доступ не тот), исправление документа — часть постмортема, а не факультативное дополнение. Именно инциденты — самый надёжный источник правды о реальном состоянии системы, потому что там расхождение проявляется само, без сверки.

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

Признаки того, что документация уже неактуальна

Не всегда очевидно, когда документ пересёк грань между «немного устарел» и «вреднее, чем его отсутствие». Несколько практических сигналов, по которым это видно раньше, чем случится инцидент из-за неверной информации:

Последний пункт — самый показательный. Если опытные инженеры молча перестали открывать документ и вместо этого сразу лезут в конфиг через SSH, документация де-факто уже не работает, даже если формально существует. Это тот момент, когда её дешевле пересобрать заново по актуальному состоянию системы, чем латать построчно — заброшенная на полгода-год документация обычно требует не сверки, а перезапуска с чистого листа, зато с тем же ежемесячным ритуалом сразу после.

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

Кто отвечает за ритуал и как не потерять его при смене состава команды

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

• Назначьте владельца ритуала явно, не «команда в целом». Один человек, чья зона ответственности включает пункт «раз в месяц провести сверку документации» — не обязательно тот, кто пишет всю документацию сам, но тот, кто следит, что ритуал состоялся.
• Зафиксируйте сам факт проведения, а не только результат. Короткая запись в конце документа или отдельном логе: «2026-08-29: сверка проведена, найдено и исправлено 3 расхождения» — отличает «ритуал реально идёт» от «документ давно никто не открывал, но выглядит так, будто всё в порядке».
• При передаче зоны ответственности новому человеку ритуал передаётся вместе с ней явно, а не подразумевается по умолчанию. Разрыв владения — самая частая точка, где ежемесячная привычка тихо останавливается: старый ответственный ушёл, новый не знал, что это вообще его задача.
• Ритуал переживает смену инструмента документации. Если команда мигрирует с Notion на self-hosted wiki или с текстового файла на BookStack, дата следующей сверки не сбрасывается — миграция инструмента не отменяет накопленный долг актуальности, а часто как раз обнажает его, потому что при переносе контента расхождения становятся заметны.

Если инфраструктуру передаёте на аутсорс или подрядчику, актуальность документации — первое, что стоит проверить перед передачей, а не после жалобы нового исполнителя. Чек-лист именно для этой ситуации — в статье передача сервера подрядчику: чек-лист: без свежей документации приёмка почти всегда растягивается в разы, потому что новый человек восстанавливает контекст методом проб и ошибок вместо чтения документа.

Частые вопросы