«Doc as code»: как писать документацию по законам кода

«Doc as code»: как писать документацию по законам кода

Или почему техническая документация заслуживает CI/CD не меньше, чем ваш любимый микросервис

Что такое doc as code?

Это подход к документации, в котором вы работаете с ней как с программным кодом:

• используете систему контроля версий (чаще всего — git);
• храните документы в виде простых текстовых файлов (чаще всего — Markdown);
• редактируете в любом редакторе или IDE;
• ревьюите через pull requests;
• автоматически собираете и публикуете (CI/CD);
• тестируете валидность (линтеры, broken links, структура).

То есть документация становится полноправной частью вашего репозитория и пайплайна разработки.

Зачем это вообще нужно?

Переход на doc as code может решить сразу несколько проблем:

1. Документация устаревает — потому что её ведут отдельно от кода.
2. Её сложно обновлять — потому что она где-то в Confluence, а доступ к нему есть не у всех.
3. Невозможно понять, кто и зачем что-то изменил — без истории версий и контекста коммита.
4. Нет согласованного формата — каждый пишет как хочет, в чём хочет, куда хочет.

С doc as code документация:

✅ Всегда рядом с кодом

✅ Обновляется по тем же процессам, что и код

✅ Проверяется автоматически

✅ Видна всем, у кого есть доступ к репозиторию

✅ Прозрачна и воспроизводима

Как это работает на практике?

Один из популярных стеков для doc as code:

• Markdown — формат файлов.
• MkDocs / Docusaurus / Sphinx — генераторы статических сайтов из Markdown.
• Git — контроль версий, pull requests, ревью.
• GitHub Actions / GitLab CI — автосборка и деплой документации.
• Netlify / GitHub Pages / внутренний сервер — хостинг.

Пример: вы добавили новую фичу — обновили README.md и api_reference.md в той же ветке. При мёрже всё прогоняется через линтеры и автоматически публикуется на docs.myproject.dev.

На что обратить внимание при внедрении:

Выберите инструменты под свою команду

Не всем нужен Sphinx с reStructuredText. Иногда достаточно MkDocs и пары плагинов.

• Определите структуру и правила.

Например: как называть файлы, где хранить картинки, в каком формате писать API, кто отвечает за ревью.

• Обучите команду.

Проведите воркшоп или напишите гайд: как писать, где смотреть результат, как поднять доку локально.

• Интегрируйте в CI/CD.

Даже простой build+link check уже даст пользу.

• Не забывайте про читателя.

Документация — не просто артефакт, а рабочий инструмент. Пишите для людей, а не для галочки.

Когда это особенно полезно:

• Вы делаете SDK или API: тогда дока обязана меняться вместе с кодом.
• У вас open source: сообщество хочет делать pull requests и в код, и в текст.
• Вы устали от Confluence, где ничего не ищется и никто не пишет.
• Вы хотите встроить документацию в процесс разработки, а не вести её параллельно.
• У вас несколько микросервисов, и нужна единая точка входа и общий стиль.

Итого

• Подход doc as code делает документацию живой, актуальной и версионируемой, упрощает ревью, снижает барьер на вход для разработчиков, встраивает работу с текстами в ежедневную рутину команды.

А ещё это просто приятно — когда документация не отстаёт от продукта, а идёт с ним в одной ветке.