Документация как код: практическое руководство

«Документация как код» — выражение, которое звучит повсюду. В самом простом виде это означает обращение с документацией так же, как с исходным кодом: хранение в системе контроля версий, написание в виде простого текста, ревью через pull request, сборка через CI/CD. Но между идеей и её качественной реализацией есть разрыв. Это руководство описывает, что такое docs-as-code, какие подходы существуют и в чём каждый из них уступает.

Почему docs-as-code важен

У программных команд уже есть рабочие процессы для управления изменениями. Код проходит контроль версий, ревью, тестирование и развёртывание. Документация обычно нет. Она живёт в вики, Google Docs или Confluence — вне рабочего процесса разработки, поддерживаемая тем, кто не забудет её обновить.

Результат предсказуем: документация расходится с реальностью. Эндпоинт API переименован, но страница вики всё ещё ссылается на старый путь. Конфигурационная опция объявлена устаревшей, но страница в Notion говорит, что она обязательна. Никто не замечает, пока пользователь не подаст баг-репорт.

Docs-as-code решает это, встраивая документацию в тот же рабочий процесс:

• Контроль версий — каждое изменение отслеживается, атрибутируется и обратимо
• Pull request — изменения документации проверяются вместе с изменениями кода
• CI/CD — документация собирается и развёртывается автоматически при мёрже
• Ветвление — черновики документации живут в feature-ветках до готовности
• Blame — вы видите, кто написал каждую строку и когда

Сообщество Write the Docs продвигает этот подход уже много лет, и аргументы в его пользу в целом победили. Сложная часть — выбор правильного инструментария.

Три подхода к docs-as-code

1. Генераторы статических сайтов

Такие инструменты, как Docusaurus, MkDocs, Hugo и Jekyll, берут markdown-файлы из git-репозитория и собирают статический HTML-сайт. Вы редактируете файлы .md в IDE, коммитите, пушите, и CI собирает и развёртывает сайт.

Плюсы:

• Настоящий git-нативный рабочий процесс — файлы — это просто markdown в репозитории
• Быстрая сборка, дешёвый хостинг (Netlify, Vercel, GitHub Pages)
• Полный контроль над шаблонами, стилями и структурой
• Никаких зависимостей времени выполнения — на выходе статический HTML

Минусы:

• Нет веб-редактора — все должны использовать текстовый редактор и git
• Нет встроенного контроля доступа (это статический сайт)
• Нет поиска без стороннего сервиса (Algolia, Pagefind)
• Нетехнические участники не могут вносить вклад
• Управление frontmatter становится утомительным при масштабировании

Пример рабочего процесса:

# Клонируем репозиторий документации
git clone [email protected]:yourorg/docs.git
cd docs

# Создаём новую страницу
cat > docs/guides/deployment.md << 'EOF'
---
title: Deployment Guide
sidebar_position: 3
---

# Deploying to Production

Follow these steps to deploy...
EOF

# Предпросмотр локально
mkdocs serve  # или docusaurus start, hugo serve

# Коммитим и пушим — CI делает остальное
git add docs/guides/deployment.md
git commit -m "docs: add deployment guide"
git push

Это хорошо работает для документации, ориентированной на разработчиков, где каждый участник знаком с git. Но ломается, когда продакт-менеджеры, инженеры поддержки или технические писатели должны вносить правки.

2. Вики и базы знаний

Confluence, Notion, Outline, Wiki.js и BookStack предоставляют веб-редакторы с WYSIWYG-интерфейсами. Контент хранится в базе данных, пользователи редактируют через браузер.

Плюсы:

• Низкий порог входа — писать может кто угодно
• Богатые редакторы с вложениями, таблицами и медиа
• Совместная работа в реальном времени (в некоторых инструментах)
• Встроенный поиск

Минусы:

• Контент НЕ в git (или только как односторонний экспорт)
• Нет ревью через pull request для изменений документации
• Нет ветвления или staging — правки сразу публикуются
• Привязка к вендору — экспортировать из Confluence куда-либо болезненно
• История версий примитивна по сравнению с git

Эти инструменты оптимизируют удобство написания за счёт всего, что делает docs-as-code ценным. Вы можете легко писать документацию, но теряете контроль версий, ревью и связь с кодовой базой.

3. Платформы документации с синхронизацией Git

Более новая категория: платформы, которые сочетают веб-редактор с настоящей интеграцией с Git. Идея — дать нетехническим участникам WYSIWYG-интерфейс, сохраняя при этом контент в git-репозитории как единственный источник истины.

Именно такой подход использует DocPlatform. Правки, сделанные в веб-интерфейсе, создают git-коммиты. Изменения, запушенные в git из IDE, появляются в веб-редакторе. Оба направления работают — это не одностороннее зеркало.

Плюсы:

• Веб-редактор для нетехнических участников
• Контент живёт в git — pull request, ветвление, blame — всё работает
• Поиск, контроль доступа и публикация встроены
• Нет этапа сборки — опубликованная документация обновляется при сохранении

Минусы:

• Двунаправленную синхронизацию сложно сделать правильно (см. Почему инструменты документации ломают синхронизацию с Git)
• Меньше вариантов шаблонов, чем у статических генераторов
• Нужно запускать сервер (в отличие от статического хостинга)

Сравнительная таблица

Практические паттерны

Какой бы подход вы ни выбрали, эти паттерны делают docs-as-code более эффективным:

Размещайте документацию рядом с кодом

Помещайте документацию в тот же репозиторий, что и код, который она описывает, или хотя бы в ту же GitHub-организацию с перекрёстными ссылками. Когда разработчик меняет API-эндпоинт, документация для этого эндпоинта должна быть видна в том же PR.

Используйте frontmatter единообразно

Каждая страница документации должна иметь структурированный frontmatter:

---
title: "API Authentication"
description: "How to authenticate with the DocPlatform API using JWT tokens"
last_reviewed: 2026-02-15
owner: "@backend-team"
---

Поля last_reviewed и owner не являются стандартными полями Hugo — это пользовательские метаданные. Но они позволяют легко находить устаревшую документацию и знать, к кому обращаться.

Автоматизируйте проверку актуальности

Настройте CI-задачу, которая помечает документацию, не проверявшуюся 90 дней:

#!/bin/bash
find docs/ -name "*.md" -exec grep -l "last_reviewed" {} \; | while read f; do
  reviewed=$(grep "last_reviewed" "$f" | cut -d'"' -f2)
  if [[ $(date -d "$reviewed" +%s) -lt $(date -d "-90 days" +%s) ]]; then
    echo "STALE: $f (last reviewed $reviewed)"
  fi
done

Не ставьте планку слишком высоко

Главная ошибка docs-as-code — делать вклад слишком сложным. Если ваш шаблон PR требует ревью стилей, проверки ссылок, проверки орфографии и двух одобрений — люди перестанут писать документацию. Держите планку низкой для изменений контента. Строгое ревью оставьте для структурных изменений.

Место DocPlatform

DocPlatform создан для команд, которые хотят docs-as-code, не заставляя всех работать в командной строке. WYSIWYG-редактор берёт на себя написание. Git обеспечивает контроль версий. Паттерн Content Ledger обеспечивает двунаправленную синхронизацию, чтобы ни одна сторона не перезаписывала другую.

Community Edition бесплатен и работает на вашем сервере — установите за пять минут одним бинарным файлом. Если вам нужен управляемый хостинг, облачные тарифы начинаются от $0 для небольших команд.

Сложная часть docs-as-code никогда не была в философии. Она была в инструментарии. Статические генераторы работают для разработчиков, но исключают всех остальных. Вики включают всех, но отказываются от контроля версий. Правильный ответ — и то, и другое: интерфейс для написания, которым могут пользоваться нетехнические люди, с git-рабочим процессом, которому доверяют разработчики.