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

А так... Чем больше проект тем абстрактнее должен быть входная точка. Легко ссылаться на документацию в коде, если у тебя один микросервис . А когда у тебя их 20? А какой нужен для чего? А есть ли у нас уже что-то что делает ааа? В коде искать ответы на такие вопросы - обалдеешь.
Так что в идеальном мире документации ровно столько, сколько надо. От 10 шкафов для программки, которая будет работать на АЭС до 5 строчек "как запустит и какие параметры" для скриптика delete_all_images.

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

все вопросы выше по доступности и эскаляции и фоллбэкам решаются на ура service team. Они отвечают на эти вопросы, организуют oncall ротации, кому звонить и как себя вести при инсиденте. Кто координирует устраненние, связывается со стекхолдерами, кто дебажит и тд.Они же потом проводят пост мортемы и вместе с девелоперами составляют юзерсторис. Работает на ура и в той команде было майкросервисов больше 20 плюс одна часть всей команды сидела в мюнхене а другая на украине. Я такой дисциплины и обработки инсидентов не видел ни в одном концерне.

диаграммы кстати всегда делались