Docs-as-Code: подход и инструменты
Документация в git, рядом с кодом: как это меняет культуру
Документация, которая врёт
В корпоративной вики почти наверняка есть страница «актуальная архитектура сервиса авторизации», которую последний раз трогали в 2022 году. На диаграмме два из пяти сервисов давно выпилены, а трёх новых там нет вовсе. Никто эту страницу не обновляет, потому что для обновления нужно открыть отдельный инструмент, вспомнить пароль, найти страницу в дереве из трёхсот вложенных разделов, отредактировать — и code review на эти правки никто делать не будет, ведь вики живёт своей жизнью, отдельной от кода. Исследование DX (бывший GetDX) 2024 года показало, что проблемы с документацией обходятся в 15–25% инженерной ёмкости — для команды на сто человек это пятнадцать-двадцать пять инженеров, которые компенсируют пробелы и устаревший контент болтовнёй в чатах, чтением исходников и обрывками 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 добавляет такую типографику и навигацию, что документация смотрится лучше многих продуктов. От установки до работающего сайта — пять минут, и в этом главный плюс: порог входа минимальный.
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 раскрывается, когда поверх Markdown-файлов добавляются CI-проверки. Минимальный набор: markdownlint для единообразия форматирования, markdown-link-check для битых ссылок, сборка сайта документации как gate «ничего не сломано». Продвинутый набор: vale для проверки стиля текста по настраиваемым правилам (запрет пассивного залога, ограничение длины предложений), проверка орфографии, автогенерация changelog из коммитов.
Дальше можно блокировать мёрж PR, если изменения в API-контрактах не сопровождаются обновлением документации. Часть команд настраивает CODEOWNERS так, чтобы правки в определённых директориях требовали approve от технического писателя.
Главное возражение и ответ на него
Типичное возражение звучит так: «разработчики не будут писать документацию, им за это не платят и в KPI этого нет». Docs-as-code отвечает на это не мотивационными речами, а снижением барьера. Когда документация — это Markdown-файл в том же репозитории, а не отдельная система с отдельным логином, дописать три абзаца к своему PR становится таким же привычным действием, как написать commit message. Не потому что появилась любовь к документированию, а потому что задача перестала требовать переключения контекста.
Write the Docs — глобальное сообщество, проводящее конференции в Портленде, Праге, Австралии и онлайн с 2013 года, — показало, что docs-as-code работает в организациях от стартапа до Google. Реальный вопрос не «подходит ли», а «сколько ещё корпоративная вики может врать, прежде чем из-за неё кто-то сломает продакшен».