в идеальном мире документация и не нужна.

Не канает. Только в микроскопических проектах без окружения. Комментарии в коде это уже документация. Против которой, собственно, и воют 95% "аджайл-девелоперов". Что характерно, против нарисованных мной деплоймент диаграмм никто не возмущался. Только спрашивали где они лежат.

Пример: наш сервис обращается к рест-сервису. Кто за него отвечает? С кем у нас договор? Кто-то гарантирует 99,999% доступность, и вообще какое у нас SLA? Если он недоступен, что мы делаем? Кому звонить?Или не надо? Переходим на резервный, игнорируем, сами перестаём что-либо обрабатывать? Где всё это документировать?

А так... Чем больше проект тем абстрактнее должен быть входная точка. Легко ссылаться на документацию в коде, если у тебя один микросервис . А когда у тебя их 20? А какой нужен для чего? А есть ли у нас уже что-то что делает ааа? В коде искать ответы на такие вопросы - обалдеешь.

Так что в идеальном мире документации ровно столько, сколько надо. От 10 шкафов для программки, которая будет работать на АЭС до 5 строчек "как запустит и какие параметры" для скриптика delete_all_images.

А, да, для IaC документация архиважна. 2-3 картинки экономят часы и дни, когда разбираешься в новом проекте. А то бывает с переходом на новую версию меняется логика команд. В паппете, по-моему, нас такое подкосило. Была бы парочка диаграммок, в разы веселее переписывать было бы.