Перейти к основному содержимому

Docs as Code: главное

Что это такое​

Docs as Code – это подход к созданию и сопровождению документации, при котором для работы с документами используются те же инструменты и процессы, что и для программного кода. Текст пишут на языке разметки (Markdown, AsciiDoc), хранят в Git-репозитории и собирают с помощью генераторов сайтов (например, GitLab Pages, Docusaurus, Antora). Публикуемая версия всегда синхронизирована с кодом и доступна потребителям.

Идея в том, чтобы обращаться с текстом документации так же, как с исходным кодом приложения: хранить его в системе контроля версий, проверять изменения через pull request’ы, автоматизированно собирать и публиковать и т.д. Другими словами, документация разрабатывается как код.

Документация может храниться как в одном репозитории с кодом, так и в отдельном - но всегда должна быть актуальной и согласованной с кодом (как и наоборот).

Суть подхода Docs as Code​

  • документация хранится в репозитории Git (см. где хранить)
  • документация пишется в IDE (VS Code или IDEA) с настроенными плагинами
  • документация пишется на выбранном языке разметки, диаграммы описываются в формате кода (plantUML, mermaid и др.)
  • документация собирается при помощи генератора сайтов (например Docusaurus)

Принципы написания документации в Docs as Code​

Написание спецификаций следует принципам написания кода, но имеет свои специфичные принципы.

Принципы, унаследованные из разработки​

ПринципСутьКак выглядит на практике
DRY (Don’t Repeat Yourself)Не дублируем информацию: один факт — один источник, остальные ссылаются.Фрагменты вынесены в инклюды; диаграммы собираются из общих блоков.
KISS (Keep It Simple, Stupid)Держим форму и язык простыми, без лишних деталей.Один файл отвечает за одну идею. Никаких лишних уровней вложенности.
YAGNI (You Aren’t Gonna Need It)Пишем только то, что нужно прямо сейчас; гипотезы и «на будущее» убираем.Пишем только то, что реально требуется пользователям или команде.
SRP (Single Responsibility Principle)Один раздел — одна тема или функция.У каждого раздела одна ответственность: API, бизнес-процесс, архитектура.
SLAP (Single Level of Abstraction Principle)Уровни абстракции не смешиваем: обзор и детали храним раздельно.Разные уровни абстракции — разные документы: C4 > компоненты > классы.
LoD (Law of Demeter)Ссылаемся только на ближайший нужный контекст, избегаем дальних зависимостей.Ссылки ведут только на ближайший нужный контекст.

Принципы, специфичные для написания спецификаций​

  1. Общие правила читабельности — короткие абзацы, активные глаголы, минимум терминов
  2. Документация предполагает единый стиль кодирования, включая структуру текста, отступы, пробелы и т.д. для облегчения понимания. Для этого разрабатываются единые шаблоны документации и готовые переиспользуемые блоки кода.
  3. Диаграммы как код — PlantUML, Mermaid, LikeC4: диаграммы генерируются из текста
  4. Автоматизация пайплайна — CI проверяет орфографию, битые ссылки, формат
  5. Отслеживание изменений, обновлений и исправлений в документах при помощи Changelog для понимания эволюции проекта
  6. Актуальность — опубликованная версия документации является актуальной (соответствует тому, что доступно потребителям на проде)
  7. Merge Request, вливаемые в master, проходят ревью - без получения аппрува сделать mr нельзя (если задача требует specification review, оно должно быть пройдено на соответствующем этапе разработки)
  8. Merge Request с изменениями в документации привязываются к задачам в Jira

Где хранить: отдельный репо или рядом с кодом​

1. Рядом с кодом​

Документация лежит в том же репозитории, что и сервис, обычно в каталоге /docs.

  • Версионирование: каждая ветка и тег кода несут свою версию текстов.

  • Плюсы:

    • Единый MR: в одном Pull Request можно сразу поправить код и ТЗ.
    • Авто-freeze: при выпуске продукта документ “замораживается” вместе со сборкой.
    • Пример: GitLab хранит руководство пользователя в том же репозитории, чтобы изменения в продукте и тексте шли синхронно.

  • Минусы:

    • Репозиторий растёт быстрее, а CI-сборки — дольше.
    • Доступ к документации требует доступа к коду, что не всегда удобно для бизнес-пользователей.

2. В отдельном репозитории​

Документация развивается в своём проекте (или нескольких), независимом от исходников сервисов.

  • Когда подходит:

    • Доков много, они обслуживают сразу несколько продуктов.
    • Требуется выпускать или править тексты без привязки к релизам кода.

  • Плюсы:

    • Бизнес-и QA-команда может работать с текстами без доступа к коду.
    • CI генерации документации не тормозит пайплайны основного продукта.
    • Поддержка агрегированных сайтов (Antora, мульти-repo Docusaurus).

  • Минусы:

    • Версионирование нужно настраивать вручную: ветки и теги документации должны соответствовать версиям продукта.
    • Правила связи MR ↔ задача Jira придётся прописывать в процессах.

Выбирайте вариант хранения, исходя из объёма документации, частоты релизов и составов команд, но обязательно следите за версионированием, интеграцией с Jira и понятной структурой файлов ― тогда управление ТЗ и спецификацией реализации станет максимально прозрачным и удобным.

Преимущества и недостатки Docs as Code​

Преимущества​

  1. Синхронность ТЗ и кода Спецификация (ТЗ) и реализация живут в одном репозитории. Правка API-контракта, базы данных и описания бизнес-правил делается в одном MR — к релизу документация и код «замораживаются» вместе.

  2. Гибкое версионирование и трассируемость Git-ветки и теги позволяют вести документацию для параллельных версий продукта (main, release/2.5). Каждое изменение имеет автора, дату и ссылку на задачу в Jira.

  3. Единый процесс работы Аналитик, разработчик и QA используют одни и те же инструменты — IDE, Git, CI. Definition of Done включает обязательное обновление ТЗ, поэтому документация никогда не отстаёт от кода.

  4. Автоматическая сборка и публикация CI/CD конвейер генерирует статический сайт (Docusaurus, Antora), проверяет орфографию, битые ссылки, примеры кода и деплоит результат за минуты.

  5. Централизованное ревью и коллаборация Все правки проходят через Merge Request: inline-комментарии по строкам, прозрачное обсуждение, единый поток задач и чёткие аппрув-чеки.

  6. Повторное использование и единый источник истины Инклюды, генерация из OpenAPI/DB-схем, подтягивание актуальных фрагментов кода гарантируют, что в тексте ТЗ всегда живые примеры и нет дублирования.

Недостатки​

  1. Высокий порог входа Системному аналитику без опыта работы с Git и разметкой придётся освоить терминал, конфликты и командную строку.

  2. Нет привычного WYSIWYG-редактора Отсутствует «живой» визуальный редактор — при больших правках нужно локально собирать сайт или смотреть preview, что добавляет неудобств.

  3. Нагрузка на поддержку инфраструктуры Команде приходится настраивать и обновлять IDE-плагины, генератор сайтов, CI-скрипты, хранилище медиа — роль «администраторов своей документационной платформы».

  4. Необходимость чётких процессов Без жёстких правил ветвления, ревью и обязательных проверок Docs as Code быстро превратится в обычное хранение текстов в Git без пользы.

  5. Сложности с таблицами и графикой Markdown/AsciiDoc не дают интуитивного редактора таблиц; хранение картинок требует S3/LFS, а крупные диаграммы могут замедлять сборку.

  6. Барьер для нетехнических участников Бизнес-аналитики, менеджеры и прочие заинтересованные лица могут не захотеть осваивать Git, поэтому для них нужно предоставлять веб-формы обратной связи или встроенные комментирование.

Docs as Code 🆚 Confluence​

КритерийConfluenceDocs as Code
Доступность редактированияЛюбой через браузер, WYSIWYGТолько через Git/IDE, Markdown/AsciiDoc
Синхронность с кодомРучная привязка, часто рассинхронизированаПолная: ТЗ и код в одном репозитории
ВерсионированиеБазовое, сложно вести параллельные версииGit: ветки и теги для каждой версии
ПубликацияЧасто вручную или через плагиныАвто CI/CD → статический сайт (Docusaurus, Antora)
Ревью и коллаборацияInline-комментарии, но вне GitflowMerge Request: inline, diff-ревью, обязательные чек-поинты
Порог входаНизкий, интуитивно для нетехнарейВысокий: требует навыков Git и терминала
Таблицы и медиаУдобный редактор таблиц, drag-&-dropТекстовый формат, требует S3/LFS и ручных инклюдов
Поддержка процессовЧасто не жестко регламентированаВстроена в Gitflow: строгие правила ветвления и мерджей
СтоимостьПлатная лицензия AtlassianOSS, но собственная поддержка инфраструктуры

Как понять, что Docs as Code хорошо работает​

  • Документация соответствует коду на проде - опубликованная версия документации является актуальной
  • Поддерживается документация для разных версий: документация в ветках (по задачам в работе), и актуальная версия (по задачам в проде)
  • Легко и просто найти изменения, которые были сделаны в документации в рамках задачи на разработку - по ссылке из Jira перейти на mr в репозиторий документации, и просмотреть изменения с историей
  • Внести изменения в документацию может любой член команды, не только SA
  • К ревью спецификаций может подключиться любой член команды, через знакомый всем процесс комментирования MR
  • Качество документации улучшилось (за счет того, что полностью все публикуемые изменения проходят ревью)
  • Время, затрачиваемое на написание документации по задаче сравнимо с показателями до внедрения практики (такое же или лучше)
  • Сократились затраты на поддержание актуальности документации

Материалы​

Наши статьи​

Статьи​

Доклады из конференций​

Примеры реализации​