Docs-as-Code: подход и инструменты

Документация, которая врёт

У вас наверняка есть Confluence-страница, которую последний раз обновляли в 2022 году, и там написано «актуальная архитектура сервиса авторизации» с диаграммой, на которой два из пяти сервисов давно удалены, а три новых не появились. Эту страницу никто не обновляет, потому что для этого нужно зайти в отдельный инструмент, вспомнить пароль, найти нужную страницу в дереве из трёхсот вложенных разделов, отредактировать — и при этом code review на эти изменения никто делать не будет, потому что вики живёт своей жизнью, отдельной от кода. Исследование DX (бывший GetDX) 2024 года показало, что проблемы с документацией обходятся в 15–25% инженерной ёмкости — на команду из ста человек это пятнадцать-двадцать пять инженеров, которые компенсируют отсутствие или неактуальность документации разговорами в Slack, копанием в коде и обрывками tribal knowledge.

Docs-as-code — это подход, который решает эту проблему за счёт одной идеи: документация хранится в тех же репозиториях, в том же формате и проходит через те же процессы, что и код. Markdown-файлы лежат рядом с исходниками, изменения проходят через pull request, CI проверяет ссылки, линтеры следят за стилем, а деплой документации происходит вместе с деплоем продукта.

Что это значит на практике

Эрик Хольшер, создатель Read the Docs и один из основателей сообщества Write the Docs, сформулировал docs-as-code как философию: документация заслуживает тех же инженерных практик, которые вы применяете к коду. Версионирование через Git. Рецензирование через pull requests. Автоматическая сборка через CI/CD. Тестирование через линтеры и валидаторы.

На практике это выглядит так: в репозитории вашего сервиса рядом с src/ появляется папка docs/, в ней — Markdown- или MDX-файлы с описанием архитектуры, API, runbook’ов, ADR. Когда разработчик меняет поведение API, он обновляет документацию в том же pull request — и ревьюер видит оба изменения рядом, может проверить их согласованность. CI-пайплайн прогоняет markdownlint, проверяет битые ссылки через markdown-link-check, а при мёрже в основную ветку автоматически собирает и деплоит сайт документации.

Squarespace описали свой путь к docs-as-code в инженерном блоге в 2025 году, и их главный вывод оказался не про инструменты, а про побочные эффекты: когда диаграммы архитектуры лежат рядом с кодом и обновляются через PR, команда начала замечать расхождения между задуманной и реальной архитектурой гораздо раньше, а трассируемость изменений — кто, когда и почему поменял документацию — стала такой же прозрачной, как для кода.

Инструменты для сборки документации

Docs-as-code — это философия, а конкретные инструменты сборки вы выбираете под свой стек и потребности.

MkDocs с темой Material — стандартный выбор для Python-проектов и не только. Конфигурация в одном YAML-файле, Markdown-контент, поиск из коробки, мобильная адаптация. Material for MkDocs добавляет такую типографику и навигацию, что документация выглядит лучше, чем у многих продуктов. MkDocs стартует за пять минут, и это его главное преимущество — порог входа минимальный.

Sphinx — ветеран из мира Python, используется для документации CPython, Django, Linux kernel. Поддерживает reStructuredText (более мощный, чем Markdown, но менее интуитивный), автоматическую генерацию API-документации из docstrings, перекрёстные ссылки между проектами. Если вам нужна семантическая разметка и автогенерация из кода — Sphinx до сих пор сильнее остальных.

Docusaurus от Meta — выбор для JavaScript/TypeScript-экосистемы. Поддержка версионирования документации, интернационализации, интеграция с Algolia для поиска. Позволяет встраивать React-компоненты в документацию, если вам нужна интерактивность. Сложнее в настройке, чем MkDocs, зато лучше масштабируется для больших проектов с несколькими версиями.

Есть ещё VitePress, mdBook (для Rust-экосистемы), Hugo с темами для документации — выбор инструмента вторичен по сравнению с самим решением хранить документацию рядом с кодом.

CI для документации

Главная ценность docs-as-code проявляется, когда вы добавляете CI-проверки. Минимальный набор: markdownlint для единообразия форматирования, markdown-link-check для поиска битых ссылок, сборка сайта документации как проверка, что ничего не сломано. Продвинутый набор: vale для проверки стиля текста по настраиваемым правилам (запретить пассивный залог, ограничить длину предложений), проверка орфографии, автоматическая генерация changelog из коммитов.

Можно пойти дальше и блокировать мёрж PR, если изменения в API-контрактах не сопровождаются обновлением документации — некоторые команды настраивают CODEOWNERS так, чтобы изменения в определённых директориях требовали approval от технического писателя.

Главное возражение и ответ на него

«У нас разработчики не будут писать документацию, им за это не платят и это не входит в их KPI» — типичное возражение звучит именно так. И docs-as-code на него отвечает не мотивационными речами, а снижением барьера. Когда документация — это Markdown-файл в том же репозитории, а не отдельная система с отдельным логином, написать три абзаца описания к своему PR становится таким же естественным действием, как написать commit message. Не потому что разработчик вдруг полюбил документирование, а потому что это перестало быть отдельной задачей с переключением контекста.

Write the Docs — глобальное сообщество, которое с 2013 года проводит конференции в Портленде, Праге, Австралии и онлайн — показало, что docs-as-code работает в организациях размером от стартапа до Google. Вопрос не в том, подходит ли вам этот подход, а в том, сколько ещё ваша Confluence-вики может врать, прежде чем кто-то из-за неё сломает продакшен.