Software Architect · Модуль 18
Архитектурная документация нужна не для архива. Она должна помогать новым людям понять систему и старым людям вспомнить причины решений.
ADR · C4 · runbook · decision record · context
Документировать нужно не только итог, но и контекст: почему выбрали так, какие альтернативы отвергли и когда решение пересматривать.
ADR фиксирует решение во времени
Фотография стройки не заменяет проект, но помогает понять, почему стену поставили именно здесь.
Architecture Decision Record обычно содержит context, decision, consequences, alternatives и status. Он не должен быть длинным. Его задача — сохранить reasoning.
Через год команда может не помнить, почему выбрала Postgres, почему отказалась от Kafka или почему сделала sync API. ADR позволяет не повторять один и тот же спор заново без исторической памяти.
Диаграмма должна отвечать на вопрос
Карта метро не показывает канализацию, потому что пассажиру это не нужно. Хорошая диаграмма тоже выбирает уровень детализации.
C4 model полезна как набор уровней: context, container, component, code. Для stakeholder-а нужен context. Для команды — containers и важные components. Для incident response — runtime view и зависимости.
Одна огромная диаграмма «всей системы» обычно бесполезна: она либо устаревает, либо становится нечитаемой.
Хорошая документация живёт рядом с изменениями и имеет владельца.
Пример: ADR для выбора очереди
В протоколе совещания важно не только решение, но и почему другие варианты не подошли.
ADR описывает: нужно доставлять domain events с replay, ordering by key и устойчивым storage. Рассматривали RabbitMQ, managed Kafka и database outbox. Выбрали managed Kafka для high throughput, но приняли цену операционной сложности и schema governance.
Такой документ помогает будущей команде понять, когда решение всё ещё верно, а когда контекст изменился.
Антипример: Confluence как кладбище
Склад старых инструкций выглядит солидно, пока никто не знает, какая инструкция актуальна.
Документация живёт отдельно от кода, не имеет owner-а, не обновляется при PR и содержит скриншоты трёхлетней давности. Новички быстро учатся её игнорировать.
Лучше меньше документов, но с понятным lifecycle: owner, last reviewed, link from code, update required for architectural change.
- Какие решения требуют ADR? - Какая диаграмма нужна новичку в первый день? - Какие runbooks нужны on-call? - Как команда узнаёт, что документ устарел?