Design Doc

В этой главе мы завершаем модуль, посвящённый проектированию, и говорим о важнейшем инструменте любого архитектора — документе проектирования (Design Doc).

Design Doc — это неформальный документ, в котором мы описываем своё решение архитектурной или технической задачи. Его цель — сформировать единое понимание будущего решения и получить обратную связь ещё до начала реализации. Он помогает нам:

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

Условно, дизайн доки можно разделить на два основных типа :

1. High-Level Design Doc (Высокоуровневый дизайн) – описывает архитектуру системы в целом или решение на уровне системы.
2. Low-Level Design Doc (Низкоуровневый дизайн) – детально описывает реализацию конкретной функции.

Низкоуровневые документы могут включать псевдокод, макеты API или типы данных. Высокоуровневые документы дают контекст и обзор архитектуры.

Рекомендуемая структура Design Doc

Если в вашей компании нет шаблона — воспользуйся этим простым вариантом:

1. Overview (Обзор) Короткое (1–2 абзаца) описание проблемы и сути документа.

2. Context (Контекст) Всё, что нужно знать для понимания решения: диаграммы контекста, детали проекта, ограничения.

3. Goals & Non-Goals (Цели и Нецели) Чётко перечисленные цели документа — что будет решено. Нецели — что сознательно исключено из обсуждения.

4. High-Level Design (Высокоуровневая архитектура) На этом уровне можно использовать:

• контейнерную диаграмму (C4 Level 2),
• описание архитектурного стиля,
• ключевые модули системы,
• высокоуровневые решения.

1. Considered Alternatives (Альтернативы) Перечень вариантов, которые рассматривались, и объяснение, почему выбран именно текущий подход.

2. Detailed Design (детализация — опционально) Используется в LLD:

• псевдокод,
• описание алгоритмов,
• схемы данных,
• диаграммы потоков.

1. Timeline (Сроки) Примерная оценка сроков. Даже приблизительная оценка помогает выявить риски.

2. Risks & Open Questions (Потенциальные риски и вопросы) неопределённости, внешние зависимости, вопросы к backend, product или дизайнерам.

3. Appendix (Приложения) Приложения: ссылки на спецификации, диаграммы, исследования, требования.

Пример дизайн документа для FoodFleet вы можете найти по ссылке.

Советы по написанию Design Docs

• Пишите кратко. Большие документы читают хуже — а нам важно получить обратную связь.
• Думайте про читателя. Документ нужен не вам — он нужен вашей команде.
• Используйте диаграммы. Они заменяют десятки строк текста.
• Не бойтесь простоты. Doc — это инструмент для общения, а не магистерская работа.