Знание о конфигурации сервера живёт в трёх местах: в голове ветерана, в чате полугодовой давности и нигде. Первое уходит с отпуском, второе теряется в ленте, третье достаётся новенькому в ночь аварии. Превратить третий вариант в первый невозможно, но возможно превратить его в базу знаний: документация, собранная из текстов в хранилище версий, публикуемая как сайт с поиском и обновляемая вместе с конфигурацией. Два генератора статических сайтов закрывают техническую часть, а дисциплина обновления это уже культура команды. Статья разбирает принцип, выбор генератора, структуру базы, шаблоны, сборку и дисциплику актуальности.
Принцип документации как код для конфигурации
Принцип короткий: тексты документации живут в хранилище версий рядом с конфигурацией и обрабатываются теми же практиками. Коммит с описанием, история изменений, ревью от коллег, ветки для больших правок: всё, что делает код управляемым, одинаково управляет документацией. Из принципа следуют главные выгоды, и первая из них, история: правка документации датируется, атрибутируется и объясняется так же честно, как правка конфигурации.
Вторая выгода, связность. Документация в том же хранилище, что и роли развертывания, меняется вместе с ними: правка конфигурации без правки описания видна в ревью как незавершённая, и разрыв между реальностью и описанием ловится до публикации. Документация в отдельной вики такого свойства лишена: она отрывается от жизни по умолчанию и догоняет её по остаточному принципу.
Третья выгода, переносимость. Тексты в хранилище переживают смену платформ, команд и редакторов: переезд базы знаний это перенос каталога и перенастройка сборки, а не история про экспорт из закрытой системы. Формат маркировки текста, простой и читаемый как текст, не требует ничего, кроме любого редактора, и читается глазами прямо в хранилище без сборки.
Принцип ограничивает и формат мечты: документация как код это не конструктор страниц с правами доступа на каждый абзац. Доступ решается на уровне хранилища и сайта публикации, богатство оформления ограничено генератором, зато фундаментальные свойства, история, связность и переносимость, задаются конструкцией. Для конфигурационной документации обмен выгодный.
Выбор генератора Sphinx против MkDocs
Оба генератора делают одно и то же: собирают из текстов с разметкой статический сайт с навигацией и поиском. Разница в исходной среде и характере роста. Первый вырос из документации программных проектов, богат встроенными возможностями к разметке технических объектов, имеет зрелую экосистему расширений и исторически принят в крупных проектах. Второй вырос вокруг простой разметки, которая и без сборки читается как текст, и держит порог входа минимальным: маркдаун знают все, кто хоть раз правил заметку.
Для документации конфигурации выбор чаще решает разметка. Если команда живёт в маркдауне, второй генератор не требует обучения: пишешь в привычном, собираешь сайт одной командой. Если база должна включать структурированные сущности и строгие ссылки, первый даёт больше строгости, и его разметка честно требует изучения. Взвешивание занимает день на пробу обоих, и день этот окупается годами отсутствия сожалений.
Темы оформления закрывают потребности обоих лагерей: популярная тема с боковым меню, блоками предупреждений и вкладками доступна для обоих генераторов, и визуальная разница между ними в готовом виде меньше, чем принято ожидать. Сравнивать стоит не картинки, а ежедневное удобство: скорость сборки, свежесть темы, качество поиска.
Практика парков сходится к простому правилу: для чисто конфигурационной базы знаний выбирается генератор с привычной разметкой и лёгкой темой, а строгость первого генератора остаётся для смешанных баз, где документация серверов соседствует с документацией приложений. Ошибка выбора не фатальна: перенос между генераторами это конвертация разметки, и истории переездов знают счастливый конец.
Структура базы знаний по парку серверов
Структура решает, найдётся ли ответ за минуту. Три подхода борются за первенство: по серверам, по ролям и по задачам. База по серверам повторяет парк страница в страницу и удобна администратору конкретной машины. База по ролям описывает классы: веб-слой, слой баз, хранилище, и удобна команде эксплуатации. База по задачам собирает сценарии: развернуть новый узел, добавить мониторинг, разобрать аварию диска.
Живые базы смешивают все три подхода с ясным порядком. Верхний уровень повторяет роли, у каждой роли страница-карточка с перечнем серверов, а сценарии живут отдельным разделом со ссылками на роли. Пользователь идёт в базу с вопросом, и структура обязана отвечать на вопросы трёх видов: где это, что это, как это сделать. Перекрёстные ссылки связывают ответы между собой, и поиск завершает картину.
Обратная сторона структуры, её обслуживание: раздел без владельца пустеет. Поэтому структура строится по ролям ответственности: раздел роли ведёт ответственный за роль, сценарии ведут дежурные, общие страницы ведут ведущий инженер. Владение пишется на первой странице раздела, и пустующий раздел переходит тому, кто им пользуется.
Ошибкой структуры считается любая из них, требующая знания внутреннего кода страницы ради навигации. Если ответ на частый вопрос требует помнить, куда его положили, структура провалена, и пересмотр структуры по статистике поиска: что ищут чаще, то обязано лежать на видном месте, и статистика поиска это честное зеркало структуры.
Шаблоны страниц от описания сервера до инструкций
Шаблон это скелет, на котором страницы растут одинаковыми. Шаблон описания сервера начинается с карточки: имя, роль, адрес, окружение, ответственный, ссылки на соседние системы. Дальше разделы: состав установленного и настроенного, сетевые интерфейсы и порты, точки резервного копирования, особенности эксплуатации. Карточка отвечает на первичные вопросы за минуту, разделы дают глубину.
Шаблон инструкции для действий строится от результата: что получится, кому применимо, предусловия, шаги с командами, проверка результата, откат. Команды в инструкции готовы к копированию: полные, с реальными путями, проверенные на последнем исполнении. Инструкция с командами, требующими дописывания на месте, это заготовка страдания, и ревью это ловит.
Шаблон разбора аварии короток: симптом, причина, диагностика, лечение, предотвращение. Пять разделов, из которых первые два пишутся в момент разбора, а последний, после того как эмоции осели. Разборы копятся и превращаются в личный атлас парка, и их ценность растёт со временем, а не стареет.
Дисциплина шаблонов мягкая: скелет обязателен, формулировки свободны. Команда из трёх человек пишет похоже и без шаблонов, команда из тридцати без шаблонов рассыпается в стилистическое сепаратство, и шаблоны это дешевле, чем редактура каждого текста вручную. Шаблоны живут в той же базе, рядом с содержимым, и меняются через ревью как всё остальное.
Сборка публикация и поиск по базе
Сборка это одна команда: генератор читает тексты, собирает сайт в статические страницы. Локальная сборка служит предпросмотром перед коммитом, серверная сборка публикует. Автоматизация очевидна: коммит в хранилище запускает сборку на сервере публикации, и сайт обновляется сам. Конвейер из двух шагов, коммит и публикация, убивает главный враг баз знаний, отложенную актуальность.
Публикация выбирается по культуре парка: статические страницы на внутреннем сервере за балансировщиком, контейнер с сайтом, любой способ, дающий адрес и поиск. Поиск встроен в темы обоих генераторов, и его качество выше ручного оглавления на порядок: индекс собирается по всем страницам, и поиск по названию утилиты находит все сценарии, где она упоминается.
Версионирование базы повторяет версию парка: если парк живёт на двух поколениях конфигурации, база публикует обе ветки с переключателем, и администратор старого поколения не читает инструкции нового. Это тонкая настройка, и парки младше трёх лет обычно живут одной версией базы, но сама возможность встроена в принцип документации как код.
Резервная копия базы это копия хранилища, и отдельная процедура не нужна: база теряется вместе с хранилищем и восстанавливается вместе с ним. Сайт публикации пересобирается из хранилища за минуты, и потеря сайта не является потерей базы. Отсутствие отдельного критического ресурса это тихая роскошь подхода.
Дисциплина актуальности связь с изменениями
Актуальность это единственный ресурс базы, который расходуется со временем без нашего участия. Документация стареет от каждого изменения конфигурации, и дисциплина строится на связке: изменение конфигурации и правка документации это одна работа, выполненная наполовину без второй половины. Ревью смотрит на обе половины как на одно целое, и незавершённая работа возвращается автору.
Вторая связка, календарная: база проходит ревизию по расписанию, раздел за разделом, владелец подтверждает актуальность или правит. Ревизия это не перечитывание всего: владелец сравнивает раздел с реальностью по контрольным точкам, и подтверждение занимает минуты. Полугодовой цикл ревизииидёт рядом с аудитом пакетов и проверкой копий, и календарь обслуживания несёт все три ритуала вместе.
Третья связка, статистическая: страницы с частыми заходами живут дольше, покинутые страницы гниют первыми. Статистика поиска и переходов показывает, какие сценарии читают, и мёртвая страница это кандидат на пересмотр или удаление. База, в которой удаление устаревшего так же привычно, как добавление нового, остаётся компактной, а компактность это форма актуальности.
Четвёртая связка, дежурная: разбор каждой аварии заканчивается правкой базы, если разбор вскрыл устаревшее или отсутствующее. Авария это самый дорогой редактор базы знаний, и не заплатить ему за работу было бы расточительно. Правка после аварии пишется в тот же день, пока контекст свеж, и ссылка на разбор остаётся в истории коммита.
Рабочее внедрение базы знаний в команде
Внедрение базы в команде выглядит так:
- Выбор генератора по разметке команды и пробная сборка за один вечер;
- Структура по ролям с шаблонами карточек и инструкций;
- Перенос живых знаний: разборы, чаты, память ветерана в страницы по шаблонам;
- Автоматическая публикация из хранилища и адрес с поиском;
- Связка изменений конфигурации с правками страниц через ревью;
- Календарная ревизия разделов и статистика поиска как зеркало структуры.
За списком стоит признание: техническая часть внедрения это три дня, культурная это полгода. База знаний живёт, когда в неё ходят, в неё пишут и ей верят, и все три глагола поддерживаются не генератором, а привычками команды.
Итоговое суждение по подходу спокойное. Документация конфигурации как код это не мода и не тяжёлая платформа, это возврат к минимальной честности: знания о парке хранятся там же, где парк описан, версионируются там же, где меняются, и публикуются туда, где их ищут. Sphinx и MkDocs закрывают технику за выходные, команда закрывает культуру за квартал, и сервер перестаёт быть чем-то, что знает только человек, который однажды не выспался. База знаний это коллективная память, и коллективная память обязана быть больше, чем память самого усталого дежурного.
Мелкая привычка с большим эффектом: в карточке каждого сервера хранить ссылку на последнее изменение конфигурации. Строка из истории хранилища отвечает на вопрос "что тут происходило" быстрее любого архива памяти.
Отдельный вопрос возможностей базы: сноски, вкладки альтернативных путей, блоки предупреждений. Оба генератора умеют всё перечисленное, и переписывание под генератор обычно происходит само за первые месяцы, когда команда находит для каждой привычки свою разметку.