Документация как код

Updated Jul 2026

Относимся к документации как к программному обеспечению

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

Почему docs-as-code

Традиционные инструменты документации (Google Docs, Confluence, SharePoint) имеют фундаментальную проблему: они отключены от кодовой базы. Когда код меняется, документация не обновляется автоматически. Никто не замечает, когда вики-страница становится неточной. Нет процесса ревью для отлова ошибок. Нет истории версий, коррелирующей с изменениями кода.

Выбор правильного формата

Markdown

Наиболее распространённый формат для docs-as-code. Простой, читаемый как plain text, широко поддерживаемый.

Сильные стороны:

• Практически нулевой порог входа
• Читаемый без рендеринга
• Поддерживается GitHub, GitLab, Bitbucket и большинством генераторов статических сайтов
• Отличная экосистема инструментов (линтеры, форматтеры, редакторы)

Слабые стороны:

• Ограниченные возможности форматирования (нет предупреждений, вкладок или сложных макетов без расширений)
• Нет нативной поддержки включений или повторного использования контента
• Синтаксис таблиц неудобен для сложных таблиц

Лучше всего для: README-файлов, тестовой документации, runbooks, API-руководств, большинства QA-документации.

AsciiDoc

Более мощный язык разметки с нативной поддержкой сложных структур документов.

Сильные стороны:

• Нативные предупреждения (NOTE, TIP, WARNING, IMPORTANT)
• Включения (импорт контента из других файлов)
• Генерация оглавления
• Условный контент (показ/скрытие на основе переменных)
• Перекрёстные ссылки между документами

Слабые стороны:

• Более крутая кривая обучения, чем у Markdown
• Меньше поддержки инструментами, чем у Markdown
• Не поддерживается нативно рендерингом GitHub (рендерится как базовый текст)

Лучше всего для: Комплексных документов тестовой стратегии, документов стандартов, документации, требующей сложной структуры.

reStructuredText (rST)

Стандарт для документации Python. Мощный, но с самой крутой кривой обучения.

Сильные стороны:

• Нативные директивы для сложного контента
• Отлично подходит для API-документации (интеграция со Sphinx)
• Сильные перекрёстные ссылки
• Отраслевой стандарт в экосистеме Python

Слабые стороны:

• Незнакомый синтаксис для большинства разработчиков
• Менее читаемый как plain text, чем Markdown
• Меньшее сообщество за пределами Python

Лучше всего для: Тестовых фреймворков на Python, проектов, уже использующих Sphinx.

Сравнение форматов

Рекомендация для большинства QA-команд: Начните с Markdown. У него самый низкий барьер для внедрения. Переходите на AsciiDoc или rST, только если столкнётесь с ограничениями, которые расширения Markdown не могут решить.

Генераторы документации

Docusaurus

Генератор статических сайтов на React от Meta. Отлично подходит для документации проектов с версионированием.

MkDocs (с темой Material)

На Python, простой, быстрый. Тема Material добавляет отполированный интерфейс с отличным поиском.

GitBook

Коммерческая платформа с чистым интерфейсом. Хорош для команд, которые хотят хостинговое решение.

Confluence

Наиболее распространённая корпоративная вики. Не совсем docs-as-code, но может быть интегрирована.

Тестовая документация в репозитории

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

Наиболее эффективное место для тестовой документации — рядом с самими тестами.

Пример структуры репозитория:

project/
├── src/
│   ├── checkout/
│   │   ├── checkout.ts
│   │   └── checkout.test.ts
│   └── payment/
│       ├── payment.ts
│       └── payment.test.ts
├── tests/
│   ├── e2e/
│   │   ├── checkout.spec.ts
│   │   └── README.md          ← What these tests cover
│   ├── performance/
│   │   ├── load-test.js
│   │   └── README.md          ← How to run, thresholds, history
│   └── test-data/
│       ├── fixtures/
│       └── README.md          ← How test data works
├── docs/
│   ├── test-strategy.md       ← Overall test strategy
│   ├── test-environments.md   ← Environment setup guide
│   └── runbooks/
│       ├── deploy-verification.md
│       └── incident-response.md
└── README.md

Преимущества совместного размещения:

• Разработчики видят тестовую документацию, когда меняют тестовый код
• Изменения документации ревьюируются в том же PR, что и изменения кода
• Git blame показывает, кто написал документацию и когда
• Документация всегда версионно совпадает с кодом

Что размещать в репозитории vs на внешней вики

Автоматизация документации

Тестовые отчёты

Автоматизированные тестовые отчёты, генерируемые CI/CD-пайплайнами, предоставляют актуальные метрики качества без ручных усилий.

Что генерировать автоматически:

Отчёты покрытия

Отчёты покрытия могут генерироваться и публиковаться автоматически:

# Example GitHub Actions step
- name: Generate coverage report
  run: npx nyc report --reporter=html --reporter=text

- name: Publish coverage to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./coverage

Линтинг документации

Автоматизированные проверки, поддерживающие высокое качество документации:

Пример конфигурации CI для линтинга документации:

# .github/workflows/docs.yml
name: Documentation Quality
on: pull_request
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint Markdown
        uses: DavidAnson/markdownlint-cli2-action@v14
      - name: Check links
        uses: lycheeverse/lychee-action@v1
        with:
          args: --verbose docs/**/*.md
      - name: Spell check
        uses: streetsidesoftware/cspell-action@v5

Процесс ревью документации

Кто ревьюирует

Когда ревьюировать

• При изменении: Каждое изменение документации проходит через PR-ревью, как и код
• По расписанию: Ежеквартальный просмотр всей активной документации на точность и актуальность
• По триггеру: Когда происходит связанный инцидент, ревьюируйте соответствующие runbooks и документацию

Как ревьюировать документацию

Поддержание документации в актуальном состоянии

Автоматическое обнаружение устаревания

Настройте системы, которые оповещают, когда документация не обновлялась в течение определённого периода:

• На основе Git: Скрипт, проверяющий дату последнего коммита для каждого файла документации и отмечающий те, что старше 90 дней
• На основе вики: Confluence и Notion поддерживают отслеживание «последнего обновления»; некоторые поддерживают автоматические напоминания
• На основе CI: Добавьте задачу, которая запускается еженедельно и создаёт тикеты для устаревшей документации

Концепция скрипта проверки устаревания:

# Find documentation files not updated in 90 days
find docs/ -name "*.md" -mtime +90 -print

Модель владения

У каждого документа должен быть назначенный владелец. Владелец — не обязательно автор; это человек, ответственный за поддержание документа в актуальном состоянии.

Расписания обслуживания

Практическое упражнение

1. Перенесите один фрагмент тестовой документации из вашей вики в репозиторий кода. Настройте его как файл Markdown в соответствующем расположении.
2. Добавьте шаг линтинга документации в ваш CI-пайплайн (markdownlint, проверка ссылок или проверка орфографии).
3. Настройте автоматическую генерацию и публикацию тестовых отчётов для вашего проекта.
4. Создайте таблицу владения документацией для ключевых документов вашей команды. Определите документы-сироты.
5. Реализуйте механизм обнаружения устаревания: скрипт, напоминание в календаре или автоматическую проверку, отмечающую документы старше 90 дней.