Документация как инструмент проектирования
Модель и масштаб — Основы БД, опорные темы, проектирование БД, пакетная работа. Карта — о разделе.
Документация как инструмент проектирования
1. Проблема "мертвой" документации
Традиционный подход:
- Команда проектирует систему,
- Пишет код,
- По завершении — создаёт документацию для сдачи заказчику или архивирования.
Результат — документация:
- Устаревает через неделю после деплоя,
- Не отражает реальных компромиссов,
- Не помогает новому разработчику понять почему система устроена так, а не иначе,
- Используется только для аудита.
Это не документация — это археологический артефакт.
Хорошая документация — living artifact:
- Создаётся до и во время проектирования,
- Меняется вместе с системой,
- Используется ежедневно командой (не только техписами),
- Автоматизирована там, где возможно.
2. Типы документации в жизненном цикле проектирования
Документация делится по цели и аудитории.
2.1. Контекстная документация (Context)
Цель — объяснить зачем система существует, какие проблемы решает, в каком окружении работает.
Аудитория — новые разработчики, менеджеры, архитекторы, заказчики.
Формат:
- C4 Model — Уровень 1 (System Context Diagram) — система как чёрный ящик, окружённый акторами (пользователи, внешние системы).
- ADR (Architectural Decision Record) — фиксация ключевых решений с аргументами за и против.
- Non-functional Requirements — измеримые NFR, как обсуждалось в предыдущем разделе.
Пример ADR:
## [ADR-003] Выбор Event Sourcing для Order Service
### Статус
Принято 15.03.2025
### Контекст
Требуется аудит всех изменений заказа, поддержка временных запросов ("какой был статус 10.03?"), и компенсация ошибок через replay.
### Варианты
1. **CRUD + Audit Table**
- Плюсы: простота, знакомая модель
- Минусы: сложность временных запросов, риск рассогласованности аудита
2. **Event Sourcing**
- Плюсы: полная история, replay, естественная интеграция через события
- Минусы: сложность чтения, необходимость проекций
### Решение
Выбран Event Sourcing. Чтение реализуется через CQRS (материализованные представления).
Такой ADR живёт в репозитории (/docs/adr/003-order-event-sourcing.md) и становится частью кодовой базы.
2.2. Структурная документация (Structure)
Цель: показать из чего состоит система и как компоненты связаны.
Аудитория — разработчики, DevOps, SRE.
Формат:
- C4 Model — Уровень 2 (Container Diagram) — сервисы, БД, внешние API, протоколы.
- C4 Model — Уровень 3 (Component Diagram) — модули внутри сервиса (domain, application, infrastructure).
- Deployment Diagram — как компоненты разворачиваются (K8s, VM, serverless).
Ключевой принцип: диаграммы генерируются из кода или поддерживаются в актуальном состоянии вручную, но регулярно.
Инструменты:
- Structurizr — DSL для C4-диаграмм, интеграция с CI/CD,
- Mermaid — встраивается в Markdown, поддерживается в Docusaurus, Obsidian, Confluence.
- PlantUML — для сложных диаграмм с версионированием.
Пример фрагмента Mermaid для Container Diagram:
Такая диаграмма обновляется при добавлении нового сервиса как часть процесса интеграции.
Соберите Container-диаграмму интерактивно (режим C4 → Containers, шаблон "Заказы"), отредактируйте под свой проект и скопируйте Mermaid в документацию:
Play ITЗагрузка интерактивного демо…
2.3. Поведенческая документация (Behaviour)
Цель: описать как система работает в типовых сценариях.
Аудитория — тестировщики, аналитики, разработчики.
Формат:
- Сценарии использования (Use Case) — шаги, акторы, пред-/постусловия,
- Sequence Diagrams — взаимодействие объектов во времени,
- State Machine Diagrams — переходы между состояниями (например, статусы заказа).
Важно: такие диаграммы не рисуются в PowerPoint "на совещании". Они создаются до реализации — чтобы выявить логические разрывы.
Пример — sequence-диаграмма для "Отмена оплаченного заказа" покажет, нужен ли возврат средств, кто его инициирует, как обрабатывается частичная отгрузка — до написания первой строки кода.
2.4. Контрактная документация (Contracts)
Цель: зафиксировать интерфейсы взаимодействия между компонентами.
Аудитория: фронтенд/бэкенд-разработчики, внешние интеграторы.
Формат:
- OpenAPI (Swagger) — для REST,
- AsyncAPI — для событий (Kafka, RabbitMQ),
- Protocol Buffers (.proto) — для gRPC,
- JSON Schema — для DTO и форм.
Ключевой принцип: контракты — источник истины.
- Клиент и сервер генерируются из одного
.yaml/.proto, - Валидация на шлюзе (API Gateway) проверяет соответствие запроса контракту,
- Breaking change требует новой версии контракта — не тихого изменения поля.
Пример workflow:
- Аналитик + разработчик проектируют API в Swagger Editor,
- CI проверяет, не нарушает ли новый контракт обратную совместимость (spectral, openapi-diff),
- При мерже в
main— генерируются клиентские SDK и обновляется Docusaurus-документация.
2.5. Живая документация (Living Documentation)
Цель: обеспечить соответствие документации и реализации в реальном времени.
Механизмы:
- Tests as Документация — BDD-сценарии на Gherkin (
Given-When-Then) читаются как спецификация:
Сценарий: Оформление заказа с недостатком товара
Дано товар "Книга" в количестве 5 шт на складе
Когда пользователь создаёт заказ на 10 шт
Тогда возвращается ошибка "INSUFFICIENT_STOCK"
И заказ не создаётся
- API Docs from Code — Swagger-аннотации в C# (
[ProducesResponseType]) или Java (@Operation) генерируют OpenAPI-спецификацию. - Interactive Примеры — Docusaurus с плагином
@docusaurus/plugin-content-docs+redoc/swagger-uiпозволяет запускать запросы прямо из документации.
3. Инструменты для "живой" документации в Docusaurus
С учётом вашего стека (Docusaurus + Markdown), вот рекомендуемый стек:
| Задача | Инструмент | Как интегрируется |
|---|---|---|
| C4-диаграммы | Mermaid + @docusaurus/theme-classic | Встроен в Docusaurus 3+; добавьте в docusaurus.config.js: |
themeConfig: {
mermaid: { theme: { ... } }
}
```` |
| **OpenAPI** | `@docusaurus/plugin-content-docs` + `redoc` | Используйте `@redocly/docusaurus-theme-redoc`, подключите `.yaml` как страницу:
````md
# /docs/api/order.md
import Redoc from '@theme/Redoc';
<Redoc specUrl="/openapi/order.yaml" />
```` |
| **ADR** | Markdown-файлы в `/docs/adr/` | Подключите как отдельную sidebar в `sidebars.js`:
````js
adr: [{ type: 'autogenerated', dirName: 'adr' }]
```` |
| **Interactive Code** | `@docusaurus/theme-live-codeblock` | Позволяет запускать JS/TS-примеры прямо в браузере (полезно для UI-логики). |
Преимущество — вся документация — в Git, версионируется вместе с кодом, проходит ревью в PR.
---
## 4. Документация как часть Definition of Done
Чтобы документация не "откладывалась на потом", её включают в **Definition of Done** для задачи:
- [ ] Код написан и покрыт тестами,
- [ ] ADR обновлён (если было архитектурное решение),
- [ ] C4-диаграмма обновлена (если изменилась структура),
- [ ] OpenAPI-спецификация актуальна,
- [ ] Примеры использования добавлены в документацию.
Такой подход гарантирует, что документация *не отстаёт* — она *развивается вместе с системой*.
---
## 5. Практика внедрения по шагам
Если команда раньше не вела документацию как часть разработки, внедряйте поэтапно:
1. Начните с ADR для архитектурных решений и одного C4-контекста.
2. Добавьте контрактную документацию для ключевых API.
3. Подключите автоматические проверки в CI на актуальность контрактов.
4. Зафиксируйте обновление документации в Definition of Done.
Так команда получает быстрый эффект без попытки "описать все сразу".
---
## 6. Что обычно ломается и как предотвратить
- **Документация только "после релиза"** — добавляйте артефакты в PR вместе с кодом.
- **Диаграммы не обновляются месяцами** — держите короткий чек-лист обновления для структурных изменений.
- **ADR превращаются в формальность** — ограничьте ADR одной страницей и фокусом на причинах выбора.
- **Контракты API расходятся с реализацией** — генерируйте спецификацию из кода или валидируйте через contract tests.
---
## 7. Мини-шаблон страницы решения
Удобный минимальный формат для **Architecture Decision Record** (ADR) в смысле *программной* архитектуры — не путать с "архитектурным решением" как разделом строительной документации здания. В веб-бэкенде аббревиатура **ADR** ещё означает паттерн Action–Domain–Responder — см. [GRASP и ADR (веб)](/encyclopedia/7-project/7-06-proektirovanie-i-arhitektura/design/2139).
Запись фиксирует **почему** выбрали вариант, а не только диаграмму:
- Контекст и ограничение.
- Рассмотренные альтернативы.
- Выбранное решение и критерии.
- Последствия и риски.
- Ссылки на связанные статьи и артефакты.
Этот формат помогает держать фокус на полезной информации и избегать академической перегрузки.
---
## Смежные материалы
- [Проектирование под нефункциональные требования](1116.md)
- [Оценка архитектурных альтернатив](2141.md)
- [Threat modeling](2142.md)
- [Проектирование сервисов и методов](1113.md)
---