Чем дольше работаю с проектами, тем больше убеждаюсь: проблема документации вовсе не в том, что разработчики или аналитики ленятся ее писать.

Проблема в процессе.

Подумайте, как обычно происходит разработка. Код проходит code review. Тесты запускаются автоматически. Есть CI/CD, проверки качества, обязательные согласования.

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

Ее обновление почти всегда существует как отдельная задача. И именно поэтому она начинает отставать от системы.

Не потому, что кто-то безответственный.

Просто любая задача, которая не встроена в процесс разработки, рано или поздно начинает проигрывать задачам, которые в этот процесс встроены.

Наверняка многие сталкивались с этим.

Перед изменением функциональности открываешь документацию. Через несколько минут понимаешь, что она уже не отражает реальное состояние системы. Дальше начинается знакомый квест: сначала идешь к разработчику и вместе с ним смотришь код, потом историю коммитов, потом задачи, переписку, Pull Request'ы... И только где-то в конце списка — документацию.

В какой-то момент я поймал себя на мысли: если самым достоверным источником информации становится код, то проблема не в качестве документации. Проблема в том, что процесс разработки никак не гарантирует ее актуальность.

Именно поэтому меня заинтересовал подход Docs as Code.

Не потому, что документация хранится в Git или пишется в Markdown. Это лишь инструменты.

Гораздо важнее сама идея: документация становится таким же артефактом разработки, как исходный код. Изменение считается завершенным только тогда, когда вместе с кодом обновилась и документация.

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

На мой взгляд, именно в этом и заключается главная ценность Docs as Code. Он решает не проблему хранения документов, а проблему организации процесса.

А как вы считаете: должна ли документация быть обязательной частью каждого Pull Request, или достаточно Confluence?