На прошлой неделе разбирались с небольшим древним сервисом.

Возник обычный вопрос: — Почему здесь асинхронное взаимодействие, а не обычный REST?

Пошли искать ответ в документации. Диаграммы были. C4, схемы интеграций, последовательности вызовов. Но почти сразу стало понятно: они отвечают только на вопрос «Как система устроена сейчас?». А нужен был совсем другой ответ: «Почему она вообще стала такой?».

Через несколько минут нашли документ с архитектурными решениями. Без UML. Без красивых схем. Пара страниц текста.

В одном из решений было написано: Рассматривали синхронное/асинхронное взаимодействие с внешней системой. Внешняя система в среднем возвращает ответ за 25 - 35 секунд, 10% запросов падают с таймаутами. Приняли решение использовать очередь.

Три минуты чтения — и обсуждение закончилось.

Тогда я поймал себя на мысли. За годы работы я видел много проектов, где документация устаревала. Это нормально. Система меняется быстрее, чем обновляются диаграммы. Но почти нигде не видел, чтобы так же тщательно сохраняли контекст принятых решений.

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

Именно эта информация исчезает первой.

Через несколько лет остается только знакомая фраза: «Ну… исторически так сложилось.»

Для меня это всегда тревожный сигнал. Не потому, что решение обязательно плохое. А потому, что команда потеряла понимание, почему оно вообще было принято.

И тогда новые люди начинают обсуждать вопросы, которые уже обсуждали несколько лет назад.

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

Куда важнее сохранить ход инженерной мысли: — какие альтернативы рассматривали; — от чего отказались; — почему приняли именно это решение.

Код можно прочитать. Диаграммы можно перерисовать.

Контекст принятия решений восстановить спустя несколько лет почти невозможно.

Если через три года команда уже не может объяснить, почему было принято то или иное архитектурное решение, значит эта часть документации уже потеряна, а возможно никогда не существовала.