← Все статьи

Docs as Code: документация в Markdown/AsciiDoc рядом с кодом

· 7 мин чтения

Что такое подход Docs as Code, почему документация в вики устаревает, как устроен процесс с текстовыми форматами, git, ревью и автоматической сборкой, чем отличаются Markdown и AsciiDoc, что делать с диаграммами и контрактами API и как внедрить подход в команде аналитиков.

Типичная судьба проектной документации: её пишут в начале проекта на вики, она аккуратно структурирована и подробна. Через полгода половина страниц не соответствует системе, никто не помнит, какие актуальны, а разработчики говорят «смотрите в коде». Причина не в лени. Документация живёт отдельно от изменений: код меняется через пул-реквест с ревью, а страница вики — когда у кого-то найдётся время. Docs as Code — подход, который устраняет этот разрыв: документация пишется, хранится, проверяется и публикуется так же, как код.

Принципы Docs as Code

  • Текстовые форматы. Документация пишется в Markdown, AsciiDoc или reStructuredText, а не в бинарных файлах Word или в визуальном редакторе вики.
  • Система контроля версий. Документы хранятся в git — в том же репозитории, что и код, или в отдельном, но с теми же практиками.
  • Ревью. Изменения документации проходят через пул-реквесты: их читают, комментируют, одобряют.
  • Автоматическая проверка. Линтеры проверяют орфографию, стиль, битые ссылки, корректность схем и диаграмм.
  • Автоматическая публикация. CI собирает сайт документации или PDF и публикует при каждом изменении.
  • Документация — часть определения готовности. Задача не считается сделанной, пока не обновлена документация, и это видно в том же пул-реквесте.

Почему это работает

Проблема вики и WordКак её решает Docs as Code
Документация отстаёт от кодакод и документация меняются в одном пул-реквесте, ревьюер видит, если документацию забыли
Непонятно, какая версия актуальнаветки и теги: документация для версии 2.3 — в теге v2.3
Нельзя посмотреть, что изменилосьпострочное сравнение в git, история с авторами и причинами
Изменения не проходят проверкуревью и автоматические проверки, как у кода
Документация к разным веткам перемешанадоработка в ветке вместе с её документацией, слияние — вместе
Зависимость от одного инструментапростой текст читается чем угодно и переживёт любую платформу

Как выглядит процесс

  1. Аналитик создаёт ветку под задачу — так же, как разработчик.
  2. Обновляет постановку, модель данных, контракт API и диаграммы — текстовые файлы в каталоге docs/.
  3. Открывает пул-реквест. Автоматические проверки: орфография, ссылки, валидность OpenAPI, сборка диаграмм.
  4. Разработчики, тестировщики и другие аналитики оставляют комментарии к конкретным строкам.
  5. После одобрения изменения сливаются, CI публикует обновлённый сайт документации.
  6. Разработка берёт задачу, имея перед собой согласованную версию требований, а изменения кода потом идут в связке с ней.

Типичная структура каталога:

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.

КритерийMarkdownAsciiDoc
Распространённостьвезде: 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 — результатом сборки.
  • «Вики удобнее для совместного редактирования». Для черновиков и обсуждений — да. Для согласованной, версионируемой документации к системе — нет.

Как внедрять

  1. Начните с одного проекта и одного вида документов — например, контракты API и ADR.
  2. Договоритесь о структуре каталога docs/ и шаблонах документов.
  3. Настройте публикацию: без удобного сайта для чтения подход не приживётся.
  4. Добавьте документацию в правила ревью: пул-реквест с изменением API без изменения контракта не принимается.
  5. Добавьте проверки постепенно: сначала сборка и ссылки, потом орфография и стиль.
  6. Перенесите актуальное, а не всё: старые страницы вики можно оставить архивом.

Итог

Docs as Code — это не про формат файлов, а про процесс: документация меняется вместе с системой, проходит ревью, проверяется автоматически и публикуется без ручных шагов. Markdown подходит для большинства документов, AsciiDoc — для больших и сложных. Диаграммы и контракты API тоже становятся текстом и живут рядом. В результате документация перестаёт устаревать «сама по себе», потому что её обновление становится частью каждого изменения.

Документацию можно писать в редакторе Markdown (гайд «Markdown-редактор онлайн», выгрузка в Word — «Markdown в Word») или в редакторе AsciiDoc (гайд «AsciiDoc онлайн»), а историю изменений артефактов проекта — смотреть в версиях (гайд «История версий»). Диаграммы как код — в PlantUML и DBML. Об уровнях архитектурных диаграмм — в статье «Модель C4».