На днях я закончил читать книгу Docs Like Code, автор Anne Gentle.

Книга содержит очень много полезного про docs as code. Нет смысла пересказывать всю книгу, поэтому я опишу те моменты, которые заинтересовали меня.

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

Чем дальше документация от кодовой базы, тем сложнее её обновлять. Заведите за правило, что merge кода невозможен без актуализации документации.

Если документация находится в одном репозитории с кодовой базой, то workflow должен совпадать с разработкой кода.

В чём docs as code выигрывает у Wiki

У docs as code можно лучше приспособить к бизнес-процессам.

Для этого нужно определиться, как будут происходить релизы и как команда будет работать с документацией.

И как процесс будет меняться с ростом команды.

Про CI/CD

CI/CD системы нужны, если документация постоянно меняется и над ней работает большая команда. Не каждый сможет заходить на сервер и запускать скрипт обновления. Опять же, постоянная сборка сокращает время, которое нужно для каждой сборки по отдельности.

Про вычитку

Для вычитки можно использовать Gerrit. Я не пробовал, но интересно.

Как убедить руководство внедрить docs as code в компании

Собрать современный адаптивный сайт с документацией и дать посмотреть его руководству.
Настроить технологии CI/CD для сборки документации. Сюда же можно подключить тесты и линтеры.
Подключить метрику и оценивать, как пользователи читают документацию и всё ли им понятно.