Типичная судьба проектной документации: её пишут в начале проекта на вики, она аккуратно структурирована и подробна. Через полгода половина страниц не соответствует системе, никто не помнит, какие актуальны, а разработчики говорят «смотрите в коде». Причина не в лени. Документация живёт отдельно от изменений: код меняется через пул-реквест с ревью, а страница вики — когда у кого-то найдётся время. Docs as Code — подход, который устраняет этот разрыв: документация пишется, хранится, проверяется и публикуется так же, как код.
Принципы Docs as Code
- Текстовые форматы. Документация пишется в Markdown, AsciiDoc или reStructuredText, а не в бинарных файлах Word или в визуальном редакторе вики.
- Система контроля версий. Документы хранятся в git — в том же репозитории, что и код, или в отдельном, но с теми же практиками.
- Ревью. Изменения документации проходят через пул-реквесты: их читают, комментируют, одобряют.
- Автоматическая проверка. Линтеры проверяют орфографию, стиль, битые ссылки, корректность схем и диаграмм.
- Автоматическая публикация. CI собирает сайт документации или PDF и публикует при каждом изменении.
- Документация — часть определения готовности. Задача не считается сделанной, пока не обновлена документация, и это видно в том же пул-реквесте.
Почему это работает
| Проблема вики и Word | Как её решает Docs as Code |
|---|---|
| Документация отстаёт от кода | код и документация меняются в одном пул-реквесте, ревьюер видит, если документацию забыли |
| Непонятно, какая версия актуальна | ветки и теги: документация для версии 2.3 — в теге v2.3 |
| Нельзя посмотреть, что изменилось | построчное сравнение в git, история с авторами и причинами |
| Изменения не проходят проверку | ревью и автоматические проверки, как у кода |
| Документация к разным веткам перемешана | доработка в ветке вместе с её документацией, слияние — вместе |
| Зависимость от одного инструмента | простой текст читается чем угодно и переживёт любую платформу |
Как выглядит процесс
- Аналитик создаёт ветку под задачу — так же, как разработчик.
- Обновляет постановку, модель данных, контракт API и диаграммы — текстовые файлы в каталоге
docs/. - Открывает пул-реквест. Автоматические проверки: орфография, ссылки, валидность OpenAPI, сборка диаграмм.
- Разработчики, тестировщики и другие аналитики оставляют комментарии к конкретным строкам.
- После одобрения изменения сливаются, CI публикует обновлённый сайт документации.
- Разработка берёт задачу, имея перед собой согласованную версию требований, а изменения кода потом идут в связке с ней.
Типичная структура каталога:
docs/
├── index.md # обзор системы
├── architecture/
│ ├── context.puml # C4: диаграмма контекста
│ ├── containers.puml
│ └── adr/ # архитектурные решения
│ ├── 0001-postgresql.md
│ └── 0002-kafka-for-events.md
├── api/
│ ├── orders.yaml # OpenAPI
│ └── events.yaml # AsyncAPI
├── data/
│ └── model.dbml # модель данных
├── features/
│ ├── checkout.md # постановки по функциям
│ └── refunds.md
└── glossary.md
Markdown или AsciiDoc
Оба формата — облегчённая разметка: текст читается как есть, а при сборке превращается в HTML или PDF.
| Критерий | Markdown | AsciiDoc |
|---|---|---|
| Распространённость | везде: GitHub, GitLab, IDE, вики, мессенджеры | меньше, но поддерживается GitHub, GitLab, IDE |
| Порог входа | минимальный | чуть выше |
| Стандарт | CommonMark + диалекты (GFM и другие), расширения различаются | единый язык, спецификация развивается в Eclipse Foundation |
| Таблицы | простые, без объединения ячеек | сложные: объединение ячеек, вложенное содержимое, ширина колонок |
| Включение файлов | нет в стандарте (только через генератор сайта) | include:: — встроено |
| Переменные, условные блоки | нет | атрибуты, ifdef/ifndef |
| Перекрёстные ссылки, сноски, оглавление | зависит от расширений | встроены |
| Блоки-предупреждения | в GFM — > [!NOTE] | NOTE:, WARNING: и другие — встроены |
| PDF и книги | через Pandoc и другие конвертеры | Asciidoctor PDF — из коробки |
Практическое правило: Markdown — для большинства документов: постановки, описания функций, ADR, README. AsciiDoc — для больших структурированных документов, которые собираются из частей и выпускаются в PDF: руководства, технические проекты по ГОСТ, документация продукта с вариантами для разных редакций.
Диаграммы как код
Docs as Code плохо сочетается с картинками из графических редакторов: PNG нельзя сравнить в ревью и неудобно править. Поэтому диаграммы тоже пишут текстом:
- PlantUML — UML-диаграммы, C4, ER, mind map, Gantt; самый полный набор;
- Mermaid — встроен в рендеринг GitHub и GitLab прямо в Markdown;
- DBML — модели данных с автоматической ER-диаграммой;
- Structurizr DSL — архитектура в модели C4;
- BPMN — исключение: формат XML, но не для ручного редактирования; хранится в репозитории и редактируется в визуальном редакторе.
При сборке документации диаграммы рендерятся автоматически: в AsciiDoc — через Asciidoctor Diagram, в генераторах сайтов на Markdown — через плагины.
Контракты API — тоже документация
Спецификации OpenAPI и AsyncAPI, схемы JSON Schema и XSD — естественная часть Docs as Code. Они хранятся в том же репозитории, проходят ревью и линтинг (Spectral, Redocly), а из них автоматически генерируется справочник API. В постановке достаточно сослаться на операцию в контракте, а не переписывать поля в таблицу — тогда таблица не разойдётся с контрактом.
Инструменты сборки
- MkDocs (с темой Material) — простой генератор сайтов из Markdown, популярен у аналитиков.
- Docusaurus — на React, с версиями документации и поиском.
- Antora — для AsciiDoc, собирает документацию из нескольких репозиториев и версий.
- Sphinx — классика для reStructuredText, поддерживает и Markdown.
- Hugo, VitePress — быстрые генераторы общего назначения.
- Pandoc — конвертер между форматами: Markdown в Word и PDF, когда нужен документ «для согласования по почте».
Проверки в CI
- орфография (cspell, Yaspeller, LanguageTool) — со словарём терминов проекта;
- стиль (Vale) — правила вроде «не использовать канцелярит», «единообразные термины»;
- битые ссылки — внутренние и внешние;
- форматирование Markdown (markdownlint);
- валидность и линтинг контрактов API;
- сборка диаграмм без ошибок;
- для контрактов — проверка обратной совместимости с предыдущей версией.
Возражения и ответы
- «Бизнес не будет работать с git». И не нужно. Бизнес читает опубликованный сайт и оставляет комментарии там или в задаче. Писать и поддерживать документацию в git будут аналитики и разработчики.
- «Аналитики не умеют git». Для работы с документацией нужны пять команд или веб-интерфейс GitLab/GitHub, где можно править файлы прямо в браузере. Это осваивается за день.
- «В Markdown нельзя сделать сложную таблицу». Можно в AsciiDoc. А очень сложная таблица часто признак того, что информацию стоит структурировать иначе.
- «Нам нужен документ в Word по ГОСТ». Его можно собирать из исходников автоматически — Pandoc или Asciidoctor с шаблоном. Исходник остаётся единственным, а Word — результатом сборки.
- «Вики удобнее для совместного редактирования». Для черновиков и обсуждений — да. Для согласованной, версионируемой документации к системе — нет.
Как внедрять
- Начните с одного проекта и одного вида документов — например, контракты API и ADR.
- Договоритесь о структуре каталога
docs/и шаблонах документов. - Настройте публикацию: без удобного сайта для чтения подход не приживётся.
- Добавьте документацию в правила ревью: пул-реквест с изменением API без изменения контракта не принимается.
- Добавьте проверки постепенно: сначала сборка и ссылки, потом орфография и стиль.
- Перенесите актуальное, а не всё: старые страницы вики можно оставить архивом.
Итог
Docs as Code — это не про формат файлов, а про процесс: документация меняется вместе с системой, проходит ревью, проверяется автоматически и публикуется без ручных шагов. Markdown подходит для большинства документов, AsciiDoc — для больших и сложных. Диаграммы и контракты API тоже становятся текстом и живут рядом. В результате документация перестаёт устаревать «сама по себе», потому что её обновление становится частью каждого изменения.
Документацию можно писать в редакторе Markdown (гайд «Markdown-редактор онлайн», выгрузка в Word — «Markdown в Word») или в редакторе AsciiDoc (гайд «AsciiDoc онлайн»), а историю изменений артефактов проекта — смотреть в версиях (гайд «История версий»). Диаграммы как код — в PlantUML и DBML. Об уровнях архитектурных диаграмм — в статье «Модель C4».
