На самом деле, любая концепция "everything as a something" это ошибка, связанная с тем, что её адепт считает всех сотрудников компании такими же, как он.
Почему документирование кодом без обычных документов плохая идея? Потому что код нафиг не упёрлось читать всем, кроме программистов.
Почему архитектурный репозиторий для всего плохая идея? Потому что всей остальной компании, кроме архитекторов, нафиг не упёрлось что-то пытаться понять в этих моделях.
Нарушается самый главный постулат - информация должна быть в формате, понятном читателю, а не писателю.
Добавлю еще такое наблюдение:
описание “в коде” констатирует как это реализовано, но не отвечает на вопрос “что должно быть реализовано и почему”. Плюс, не описывает межсервисные процессы.
Документация, в моем представлении, в первую очередь описывает:
- задачу в терминах домена прикладной области (problem domain)
- особенности прикладного домена (напр. регуляторные требования)
- требования заказчиков фнукцинальные и нефункциональные
“Документация кода” лишь помогает новичкам быстрее сориентирвоаться в проекте, упрощает передачу проекта в эксплуатацию или на сопрвождение другой команде.
Эти два класса документов практически никогда не смешиваются.