Что такое подход Docs as Code и как его применять
Что проверяют
Понимаете ли вы, что документация это часть поставки, а не файл в облачном диске. За вопросом стоит опыт аналитика, который живёт в одном репозитории с разработчиками и отвечает за то, чтобы описание не разъезжалось с работающей системой.
Как отвечать
Docs as Code это работа с документацией по правилам работы с кодом: исходник в текстовом формате (Markdown, AsciiDoc), хранение рядом с кодом под контролем версий, изменения через ветку и ревью, автоматическая сборка и публикация.
Что это даёт: у каждой правки есть автор и причина, спор идёт в комментариях к изменению, а не в переписке; правка поведения и правка описания уезжают одним изменением; битая ссылка или невалидная схема падают в проверках, а не обнаруживаются читателем.
Что кладёт туда аналитик: требования и пользовательские сценарии, короткие записи о принятых решениях, контракт интерфейса в формате OpenAPI или AsyncAPI, диаграммы текстом (PlantUML, Mermaid), глоссарий предметной области.
Порядок внедрения: выбрать формат и генератор сайта, перенести живые документы и честно выбросить мёртвые, настроить проверки (орфография, стиль, ссылки, валидность схемы), включить публикацию по слиянию, договориться, что изменение поведения без правки описания ревью не проходит.
Где спотыкаются
Заводят отдельный репозиторий только под документацию и теряют главное свойство подхода. Смысл в том, что описание едет вместе с кодом одним изменением; в соседнем репозитории оно расходится ровно так же, как расходилось в вики.
Переносят формат, но не процесс. Markdown в системе контроля версий без обязательного ревью и без проверок в конвейере это та же вики, только редактировать неудобнее.
Требуют от всех участников работать в консоли и получают тихий саботаж от тех, кто пишет раз в месяц. Таким людям нужен низкий порог входа: готовый шаблон документа, чек-лист ревью и веб-редактор поверх репозитория.