# 18. Документация

Как писать ADR, diagrams, runbooks и system context так, чтобы документация помогала принимать решения, а не устаревала через неделю.

- **Author:** Фёдор Чищин
- **Level:** advanced
- **Reading time:** ~25 минут чтения
- **Published:** 2026-05-23
- **Source:** https://fedorthinks.com/ru/learn/software-architect-18-documentation

---

## 1. Главная идея

Документировать нужно не только итог, но и контекст: почему выбрали так, какие альтернативы отвергли и когда решение пересматривать.

### 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 и зависимости.

Одна огромная диаграмма «всей системы» обычно бесполезна: она либо устаревает, либо становится нечитаемой.

## 2. Пример и антипример

Хорошая документация живёт рядом с изменениями и имеет владельца.

### Пример: 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?
- Как команда узнаёт, что документ устарел?

Следующий модуль: [Коммуникация](./software-architect-19-communication).