Docs as Code: документация с Git и Markdown

Docs as Code и Git: почему документация должна жить рядом с кодом

Представьте ситуацию: команда выпустила новую версию продукта, разработчики обновили код, но документация осталась описывать старое поведение. Пользователи читают устаревшие инструкции, поддержка тонет в однотипных вопросах, а технический писатель не знает, что именно изменилось. Это не редкость — это стандартная боль большинства команд, которые хранят документацию отдельно от кода.

Docs as Code — подход, который решает эту проблему радикально: документацию начинают вести точно так же, как программный код. Те же инструменты, те же процессы, та же дисциплина.

Почему традиционный подход ломается

Классическая схема выглядит так: документация живёт в Google Docs, Confluence или корпоративной wiki, разработчики пишут код в своих репозиториях, а технический писатель периодически «синхронизирует» одно с другим вручную. На практике эта синхронизация всегда запаздывает.

Конкретные проблемы традиционного подхода:

Нет истории изменений. Кто и когда удалил раздел про авторизацию? Почему описание API изменилось три месяца назад? В Google Docs это почти невозможно отследить.

Нет процесса ревью. Любой может отредактировать страницу в Confluence без проверки — и никто не заметит ошибку.

Документация отстаёт от кода. Код меняется в понедельник, документация — в лучшем случае в пятницу, а чаще — никогда.

Публикация ручная. Чтобы обновить сайт с документацией, нужно вручную скопировать текст, нажать кнопку, проверить форматирование.

> Документация слишком часто оказывается в конце списка задач: её начинают писать после релиза, хранят в Word или в корпоративной wiki, а затем забывают обновлять. В результате она быстро устаревает и теряет ценность. > > habr.com

Что такое Docs as Code

Docs as Code (документация как код) — это метод создания технической документации, при котором тексты пишутся в простых текстовых форматах, хранятся в системах контроля версий и проходят через те же процессы проверки и публикации, что и исходный код проекта.

Четыре ключевых принципа подхода:

| Принцип | Что это значит на практике | |---|---| | Текстовые форматы | Документация пишется в Markdown или reStructuredText, а не в Word | | Контроль версий | Файлы хранятся в Git-репозитории с полной историей изменений | | Ревью через Pull Request | Любое изменение проходит проверку коллег перед публикацией | | Автоматическая сборка | При каждом обновлении документация автоматически собирается и публикуется |

Важно понять: Docs as Code — это не конкретный инструмент, а философия работы с документацией. Вы можете использовать GitHub, GitLab или собственный сервер — суть остаётся одной.

Что такое Git и зачем он нужен

Git — это система контроля версий (version control system, или VCS). Проще говоря, это инструмент, который запоминает каждое изменение в ваших файлах: кто изменил, что именно изменил и когда.

Представьте, что вы пишете книгу и каждый день сохраняете её копию с датой в названии: book_2024-01-15.docx, book_2024-01-16.docx. Через месяц у вас 30 файлов, и вы не помните, в какой версии был тот абзац, который вы случайно удалили. Git решает эту проблему элегантно: он хранит не копии файлов, а историю изменений, и позволяет в любой момент вернуться к любой точке этой истории.

Несколько реальных сценариев, где Git незаменим:

Вы случайно удалили важный раздел документации → Git позволяет восстановить его за 30 секунд

Два человека одновременно редактируют один файл → Git помогает объединить их правки без потерь

Нужно понять, почему три месяца назад изменилось описание функции → Git покажет автора, дату и причину изменения

Репозиторий (repository, или просто repo) — это папка с проектом, за которой следит Git. Всё, что находится внутри этой папки, Git может отслеживать и версионировать.

Коммит (commit) — это «снимок» состояния файлов в определённый момент времени. Каждый коммит имеет уникальный идентификатор и сообщение, объясняющее, что изменилось. Например: "Добавил раздел про установку на Windows".

!Схема работы Docs as Code: от редактирования файла до публикации через Git

Как Git и Docs as Code работают вместе

Рассмотрим типичный рабочий процесс технического писателя в команде, которая использует Docs as Code.

Клонирование репозитория. Писатель скачивает репозиторий с документацией на свой компьютер командой git clone. Теперь у него есть локальная копия всех файлов.

Создание ветки. Перед началом работы создаётся отдельная ветка (branch) — изолированное пространство для изменений. Например, feature/add-installation-guide. Это значит, что основная документация не пострадает, пока ветка не будет проверена и одобрена.

Редактирование файлов. Писатель открывает нужный Markdown-файл в любом текстовом редакторе и вносит изменения.

Коммит изменений. После редактирования изменения фиксируются командой git commit с понятным сообщением: "Добавил инструкцию по установке для macOS".

Отправка на сервер. Командой git push ветка отправляется на GitHub или GitLab.

Pull Request и ревью. Писатель создаёт Pull Request (PR) — запрос на слияние своей ветки с основной. Коллеги проверяют изменения, оставляют комментарии, предлагают правки.

Слияние и публикация. После одобрения ветка сливается с основной, и автоматически запускается сборка — обновлённая документация появляется на сайте.

Весь этот процесс — точная копия того, как разработчики работают с кодом. Именно поэтому подход называется Docs as Code.

Markdown: почему именно он

Markdown — это язык разметки, который позволяет форматировать текст с помощью простых символов. Вместо того чтобы нажимать кнопку «Жирный» в Word, вы пишете жирный текст. Вместо выбора размера заголовка — ставите # в начале строки.

Вот простой пример: чтобы создать заголовок и список в Markdown, достаточно написать:

Это превратится в красиво отформатированный заголовок и нумерованный список на любом сайте или в любом Markdown-редакторе.

Почему Markdown идеально подходит для Docs as Code:

Это обычный текст. Файл .md можно открыть в любом редакторе — от Notepad до VS Code. Никаких проприетарных форматов.

Git отлично работает с текстом. Система контроля версий видит каждое изменённое слово, а не просто «файл изменён».

Легко читается без рендеринга. Даже «сырой» Markdown понятен человеку — в отличие от XML или HTML.

Быстро учится. Базовый синтаксис осваивается за 30 минут.

Где хранить документацию: GitHub и GitLab

GitHub и GitLab — это платформы для хранения Git-репозиториев в облаке. Они добавляют к возможностям Git удобный веб-интерфейс: можно просматривать файлы прямо в браузере, создавать Pull Request, оставлять комментарии к изменениям, настраивать автоматическую публикацию.

Разница между ними для новичка минимальна:

| | GitHub | GitLab | |---|---|---| | Популярность | Крупнейшая платформа, огромное сообщество | Меньше, но активно используется в корпоративной среде | | Бесплатный план | Есть, с публичными и приватными репозиториями | Есть, включает встроенный CI/CD | | Публикация документации | GitHub Pages — бесплатный хостинг | GitLab Pages — аналогичный функционал | | Self-hosted | Платно (GitHub Enterprise) | Бесплатно (GitLab CE) |

Для начала обучения отлично подойдёт GitHub — у него самое большое сообщество и больше всего обучающих материалов.

Кому подходит Docs as Code

Подход особенно эффективен в нескольких ситуациях, которые описывает documenterra.ru:

Продукт часто обновляется. Если релизы выходят раз в неделю, документация должна успевать за кодом — и Docs as Code позволяет это сделать.

Над документацией работает команда. Несколько писателей, разработчики, которые дополняют технические разделы, менеджеры, которые проверяют формулировки — все работают в одном репозитории без конфликтов.

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

При этом Docs as Code — не серебряная пуля. Для небольшого проекта с редкими обновлениями и командой из одного человека простая wiki может быть удобнее. Главное — понимать, какую проблему вы решаете.

Первый шаг: установка Git

Прежде чем двигаться дальше, нужно установить Git на свой компьютер. Это займёт несколько минут.

На Windows: скачайте установщик с официального сайта git-scm.com и запустите его. Все настройки по умолчанию подходят для начала.

На macOS: откройте Terminal и выполните команду:

Если Git не установлен, система предложит установить Xcode Command Line Tools — соглашайтесь. Либо установите через Homebrew:

На Linux (Ubuntu/Debian):

После установки проверьте, что всё работает:

Затем представьтесь Git — это важно, потому что каждый коммит будет подписан вашим именем и email:

Эти две команды нужно выполнить один раз — Git запомнит настройки для всех будущих проектов. Флаг --global означает, что настройки применяются глобально, ко всем репозиториям на вашем компьютере.

Поздравляем — Git установлен и настроен. В следующих статьях вы создадите свой первый репозиторий документации, научитесь делать коммиты и работать с GitHub. Но уже сейчас важно понимать главное: Docs as Code — это не сложная технология, а способ мышления, при котором документация становится таким же полноценным продуктом, как и код.