Ось інвентаризація того, що типова інженерна команда тримає в git:

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

А ось що зазвичай живе поза git:

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

Це дивно. Документація описує систему. Вона змінюється, коли змінюється система. Їй потрібне рецензування, версіонування, атрибуція та можливість відкату. Кожен інший артефакт із цими властивостями живе в git. Документація — ні, і ніхто не може дати гарне пояснення чому.

Типові відмовки

«Нетехнічні люди повинні редагувати документацію»

Це найпоширеніший аргумент на користь зберігання документації в Confluence чи Notion. І він обґрунтований — ви не можете просити продакт-менеджера вивчити git branching, щоб виправити помилку. Але це не аргумент проти git. Це аргумент на користь кращого інструментарію поверх git.

Git — це бекенд для зберігання та версіонування. Ніщо не вимагає, щоб люди взаємодіяли з ним напряму. Веб-редактор може створювати коміти та пушити зміни так само, як це робить CI-конвеєр. Користувач пише в браузері; система обробляє git-операції.

Протиставлення «git проти нетехнічних користувачів» — хибна дихотомія. Можна мати і те, і інше.

«Документація змінюється занадто часто для PR»

Деякі команди вважають, що вимога pull request для документації сповільнить написання. І якщо ваш процес PR вимагає двох рецензентів, перевірку CI та чергу на злиття — так, це занадто багато тертя для виправлення помилки.

Але ніщо в 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 endpoint, повинен включати документацію для цього endpoint. Коміт, що оголошує функцію застарілою, повинен оновити документацію в тому ж коміті — або принаймні в тому ж PR. Коли документація живе у вікі, таке зв’язування неможливе. Код поставляється, а хтось створює тікет «оновити документацію», який тижнями стоїть у беклозі.

Порівняння

Що змінилося в останніх нотатках до релізу? Покажіть diff. У 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 commit — автоматично, непомітно
  3. Розробники можуть редагувати той самий контент у своєму IDE і пушити в той самий репозиторій
  4. Обидві сторони залишаються синхронізованими — без конфліктів, без ручного злиття
  5. Pull request працюють для документації так само, як для коду
  6. Повна git-історія доступна: blame, diff, log, branch

Це не гіпотетично. Патерн Content Ledger вирішує проблему синхронізації. Платформи, що його реалізують, дають вам досвід редагування як у вікі з git-репозиторієм як бекендом.

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

Як зазначено в самій документації Git: контроль версій записує зміни файлів у часі, щоб ви могли згадати конкретні версії пізніше. Це стосується документації так само, як і коду. Можливо, навіть більше — бо код має тести для виявлення регресій, а документація має лише людську пам’ять.

Якщо ваша документація варта написання, вона варта версіонування. Покладіть її в git.

Якщо ви хочете спробувати платформу документації, де git є джерелом істини — а не доповненням — DocPlatform безкоштовний і розгортається на власному сервері. Один бінарний файл, без бази даних для управління, двостороння синхронізація з git вбудована.