Но если у тебя все хорошо - то трать ресурсы на code review.
Качество процессов почти никак не связано с результатом работы.

гораздо приятнее работать на проектах, где не экономят на качестве
когда говорят "мы понимаем, что это дорого, но сделайте не хуже чем у ХХХ (главный конкурент)"

Так code review не улучшает качества продукта же )

Спасибо, разница была в понимании масштаба решений - у меня мини решение тоже фиксируется мини доком с пояснениями, у тебя подразумевается более глобальное решение на весь продукт :)
Возможно ADR для мини не лучший формат и корректнее назвать по-другому эти доки :)

Спорный вопрос о терминологии получается, и стоит ли вообще плодить мини доки или ссылаться на техдизайны через задачи для небольших решений
С проблемой роста количества таких доков согласен, с тем что документирование Легаси отдельный процесс тоже :)

тут сложно придумать объективную метрику, поэтому непонятно как дольше спорить

code review это как мыть руки после туалета - сложно измерить, насколько это убережёт и от чего, но вроде бы все это делают
и если это в культуре - тогда всё само собой происходит

Если бы мытье рук занимало бы час, то тоже придумывали бы варианты его делать пореже )

Я не про "мини" или "макси", я про скоуп решения.
Есть то, что про бизнес-фичу, а есть то, что про продукт целиком. И для этих решений - разные документы.

Звучит логично, разным скоупам разные документы
Но у описания практики ADR я не помню чего-то про скоуп
Наверное потому и туманная что трактовать можно сильно по-разному

Поискал первоисточник
https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
Походу я не прав, речь идёт о significant decision for a specific project. It should be something that has an effect on how the rest of the project will run
ADRs have been especially useful for capturing longer-term intention

Тогда действительно насилую формат и впихиваю невпихуемое :)

А про контроль версий тоже есть
One potential objection is that keeping these in version control with the code makes them less accessible for project managers, client stakeholders, and others who don't live in version control like the development team does. In practice, our projects almost all live in GitHub private repositories, so we can exchange links to the latest version in master. Since GitHub does markdown processing automatically, it looks just as friendly as any wiki page would.

Было удобно когда жили в Azure DevOps - настроили Вики смотреть на docs в мастере, и продакт тоже мог участвовать :)

Задачи в битбакете в репо, доки там же в отдельной папке - ссылки на доки в мастере видно из задач, редактировать не очень удобно
А Вики у него вообще грустный, это отдельный связанный репо
Конфлюенса нет

@dphil А какие практики стоит использовать для документирования легаси, куда можно посмотреть?
Цель - понимать контекст решений принятых когда-то давно, при работе с легаси компонентами/подсистемами, чтобы лучше понимать как встраиваться/менять + потом проще было объяснять и шарить эти знания

Для меня сейчас главная польза от Confluence - комментарии по тексту (и нотификации о комментариях к "твоим" страницам). Это очень удобно для обсуждения. Это можно делать в виде комментариев к коду в том же битбакете, но гораздо менее удобно, на мой взгляд
Ну и pluntuml вместе с текстом сильно упрощает чтение.

Перед посещением клозета все собирались бы и обсуждали, что и какой рукой собираются держать, чтобы не замараться.

Нет ответа, я сам каждый раз что-то новое изобретаю.
Обычно стараюсь нарисовать архитектуру из своих личных viewpoint, потихоньку уточняя отдельные пункты.
Я тут люблю личные пространства в том же confliuence, но можно и свой проект в гитхабе.
А после появления пониманий - выплескивать на других и собирать обратную связь

PluntUML - чтобы описывать диаграммы декларативно, и не страдать с перерисовкой в каком-нибудь draw.io?
Хотя как я понимаю drawIO умеет в pluntuml

Ага. drawio, кажется, не умеет...
Ну и поиск по pluntuml лучше.

Но вообще нормальных инструментов описания software architecture - все еще нет (

Спасибо :) в чате архитекторов кто-то говорил что рисовал некую модель которую можно вертеть в разных проекциях в UI, приближать и видеть более детальную прорисовку вьюпоинта вглубь
Не помнишь, было такое? ArchiMate или что-то такое

Звучит круто, но хз насколько практично

В нем, наверно, можно - но очень дорого...

Еще есть вариант все рисовать в neo4j, но пока не пробовал

Забавно что книги по архитектуре от SEI и другие существуют уже десятилетия, а нормальных инструментов все ещё нет(