Вот список того, что типичная инженерная команда хранит в git:

  • Исходный код приложения
  • Описания инфраструктуры (Terraform, Pulumi, CloudFormation)
  • Конфигурации CI/CD-пайплайнов
  • Скрипты миграции базы данных
  • Спецификации API (OpenAPI, protobuf)
  • Манифесты развёртывания (Kubernetes, Docker Compose)
  • Шаблоны конфигурации окружения

А вот что обычно живёт вне git:

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

Это странно. Документация описывает систему. Она меняется, когда меняется система. Она нуждается в ревью, версионировании, атрибуции и возможности отката. Каждый другой артефакт с этими свойствами живёт в git. Документация — нет, и никто не может дать хорошего объяснения почему.

Типичные оправдания

«Нетехнические люди должны редактировать документацию»

Это самый распространённый аргумент в пользу хранения документации в Confluence или Notion. И он справедлив — нельзя просить продакт-менеджера изучить ветвление в git ради исправления опечатки. Но это не аргумент против git. Это аргумент в пользу лучших инструментов поверх git.

Git — это бэкенд для хранения и версионирования. Ничто не требует от людей взаимодействовать с ним напрямую. Веб-редактор может создавать коммиты и пушить изменения так же, как это делает CI-пайплайн. Пользователь пишет в браузере; система обрабатывает git-операции.

Противопоставление «git vs. нетехнические пользователи» — ложная дихотомия. Можно иметь и то, и другое.

«Документация меняется слишком часто для PR»

Некоторые команды считают, что требование pull request для документации замедлит написание. И если ваш PR-процесс требует двух ревьюеров, CI-проверки и merge queue — да, это слишком много трения для исправления опечатки.

Но ничто в git не обязывает к тяжёлому процессу ревью. Можно пушить напрямую в main для мелких правок и использовать ветки для структурных переписываний. Суть в том, что история существует. Каждое изменение отслеживается, атрибутируется и обратимо. Ревьюить ли каждое изменение — это решение по процессу, а не ограничение инструмента.

«Наша платформа документации не поддерживает git»

Раньше это было правдой, и это имело значение. Confluence, Notion и большинство вики хранят контент в проприетарной базе данных без настоящей интеграции с git. Экспорт в markdown теряет данные и работает только в одну сторону.

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

«Markdown ограничен»

Справедливая критика для определённых типов контента. Markdown не поддерживает сложные таблицы, встроенные диаграммы или интерактивные элементы на нативном уровне. Но для 90% внутренней документации — руководств, ранбуков, архитектурных решений, описаний API, материалов для онбординга — markdown более чем достаточен.

И markdown в git даёт то, чего не может ни один проприетарный формат: переносимость. Если через два года вы решите сменить инструмент, ваш контент — это текстовые файлы в стандартном формате. Попробуйте экспортировать пять лет контента из Confluence во что-то полезное.

Что вы теряете без Git

Если ваша документация живёт вне git, вы теряете возможности, которые инженеры принимают как должное для кода:

Blame

Кто написал этот абзац, утверждающий, что API поддерживает пагинацию? Когда? В ответ на что? С git blame вы можете проследить каждую строку до её автора, временной метки и сообщения коммита. В вики вы можете получить «последний раз редактировала Анна, 6 месяцев назад» — без контекста, зачем.

Ветвление

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

Атомарные кросс-репозиторные изменения

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

Дифф

Что изменилось в последних release notes? Покажите дифф. В git git diff v1.4..v1.5 -- docs/ показывает именно то, что изменилось. В вики вы кликаете по историям страниц одну за другой, сравнивая отрендеренный вывод и надеясь заметить каждую правку.

Автоматизация

С документацией в git можно строить автоматизацию:

# Найти документацию, не обновлявшуюся 90 дней
git log --all --diff-filter=M --name-only --since="90 days ago" -- docs/ \
  | sort -u > recently_modified.txt

# Сравнить со всеми файлами документации
find docs/ -name "*.md" | sort > all_docs.txt

# Файлы, НЕ изменённые за 90 дней
comm -23 all_docs.txt recently_modified.txt

Попробуйте сделать это с вики. Вам придётся обращаться к API, парсить временные метки и обрабатывать пагинацию — если API вообще предоставляет даты модификации.

Настоящая причина, почему документация не в Git

Она не техническая. Она историческая. Документация появилась раньше современных DevOps-практик. Вики возникли в начале 2000-х, когда «инфраструктура как код» не существовала, а контроль версий означал SVN. Модель вики — редактирование в браузере, сохранение в базу данных — имела смысл, когда альтернативой была рассылка документов Word по электронной почте.

Но инженерные практики эволюционировали. Инфраструктура перешла от вручную настраиваемых серверов к декларативному коду в git. CI/CD перешёл от Jenkins-задач, настраиваемых через веб-интерфейс, к pipeline-as-code в YAML-файлах. Конфигурация перешла от страниц настроек в приложениях к переменным окружения и конфигурационным файлам в репозиториях.

Документация — последний оплот. Не потому что она другая, а потому что инструментарий не поспевал. Статические генераторы решили проблему «документация в git» для разработчиков, но исключили всех, кто не пользуется терминалом. Вики решили проблему «писать может каждый», но отказались от контроля версий. Ни одна сторона не соединила два мира — до недавнего времени.

Как должно быть

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

  1. Авторы создают и редактируют контент через веб-интерфейс — терминал не нужен
  2. Каждое сохранение создаёт git-коммит — автоматически, незаметно
  3. Разработчики могут редактировать тот же контент в своей IDE и пушить в тот же репозиторий
  4. Обе стороны остаются синхронизированными — без конфликтов, без ручного мёржа
  5. Pull request работают для документации так же, как для кода
  6. Полная git-история доступна: blame, diff, log, branch

Это не гипотетика. Паттерн Content Ledger решает проблему синхронизации. Платформы, которые его реализуют, дают вики-подобный опыт редактирования с git-репозиторием в качестве бэкенда.

Если вы строите новый рабочий процесс для документации — или перестраиваете тот, который не работает — начните с git как фундамента. Выбирайте инструменты, которые рассматривают репозиторий как единственный источник истины, а не как цель экспорта. Ваше будущее «я», проверяющее, что и почему изменилось, будет благодарно за существование истории.

Как написано в документации самого Git: контроль версий записывает изменения файлов с течением времени, чтобы можно было вернуться к конкретным версиям позже. Это относится к документации ровно так же, как к коду. Может быть, даже больше — потому что у кода есть тесты для обнаружения регрессий, а у документации только человеческая память.

Если вашу документацию стоит писать, её стоит версионировать. Поместите её в git.

Если вы хотите попробовать платформу документации, где git — единственный источник истины, а не дополнение — DocPlatform бесплатен и работает на вашем сервере. Один бинарный файл, без управления базой данных, встроенная двунаправленная синхронизация с Git.