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

Чтобы изменения по разным задачам не пересекались по файлам, используется жёсткая структура каталогов: архитектура системы, внешние системы, внешний API, процессы, описание фронтенда и бэкенда. Для каждого типа артефактов есть шаблоны в templates/, а общие страницы подключаются через include, а не дублируются вручную.

За основу взята модель GitHub Flow: master соответствует текущему состоянию production, ветки docs/CRM-XXXX живут до релиза задачи, а короткоживущие catch/CRM-XXXX нужны, чтобы описать уже реализованную, но не задокументированную функциональность. Прямые изменения в master запрещены — только через новую ветку и Pull Request, а имена веток и коммитов формируются по шаблону и связываются с задачей.

Рабочий флоу такой: аналитик создаёт ветку, описывает изменения в.md и открывает PR, пайплайн готовит постановку и публикует её в Jira и Confluence, затем идёт опциональное ревью. Ветку docs мержат только после релиза фичи, когда спеку сверяют с реальностью, поэтому в master документация соответствует production.

Чтобы структура не вела к перфекционизму, зафиксирована глубина детализации: описывать прежде всего бизнес-логику, внутреннюю архитектуру оставить разработке, допустимы страницы-заглушки, а на разбор ранее внедрённого отводится пропорция 80/20 — 80% времени на новые фичи и 20% на техдолг.

При миграции документация из репозитория публикуется в то же пространство Confluence, где раньше велись страницы. Старые страницы можно редактировать и переносить постепенно как техдолг, новые публикуются с ограничением на редактирование и ссылкой на источник в Bitbucket. Две версии одного документа в разных системах запрещены организационно: перед написанием в Markdown оригинал переносят и удаляют старую страницу.

В следующей части цикла автор планирует построить AI-агента на основе созданных пайплайнов, редактора и правил работы с документацией.