Как написать design doc для крупной задачи и провести его обсуждение?
- Что такое design doc?
- Как согласовать архитектуру с командой?
Design doc — короткий документ до начала работы: контекст и проблема, цели и не-цели, требования (нагрузка, данные, сроки), предлагаемое решение с схемой, альтернативы и почему не они, риски и план их снятия, план внедрения и метрики успеха. Рассылается заранее, обсуждается на встрече, где решают открытые вопросы, а не читают документ вслух. Итог фиксируется — ADR или раздел «решение».
- 3–6 страниц, а не роман; схемы вместо абзацев
- Не-цели не менее важны: что мы сознательно не делаем
- Приглашать тех, кого решение затронет: соседние команды, эксплуатацию
А ещё Документ ценен обсуждением: найденная на бумаге ошибка стоит часы, в коде — недели
Подробно
Шаблон:
- Контекст и проблема.
- Цели и не-цели.
- Требования и ограничения.
- Решение: схема, данные, API, потоки.
- Альтернативы.
- Риски, безопасность, наблюдаемость.
- План: этапы, миграция, откат.
- Открытые вопросы.
Обсуждение: комментарии в документе заранее, встреча на 30–45 минут по спорным пунктам, решение и владельцы задач.
Что хотят услышать
- Структура документа.
- Альтернативы и не-цели.
- Обсуждение заранее и на встрече.
- Фиксация решения.
Проверьте себя
Один верный вариант. Подумайте, потом откройте ответ.
Показать варианты и ответ
- ✗Писать документ после реализации для отчётности
- ✗Описать только выбранное решение со схемой и планом, без альтернатив
- ✗Обсуждать только внутри своей команды, не привлекая затронутых
- ✓Цели, решение, альтернативы и риски; рассылка заранее и обсуждение открытых вопросов
Разбор темы
- Design doc, ADR и технический долг
Как написать design doc и провести обсуждение, зачем записывать решения в ADR и как договориться с бизнесом о работе с техническим долгом.
Связанные вопросы
Разбор собеседования с sotto
После собеседования sotto разбирает разговор: оценка, каждый вопрос — хорошо, частично или слабо, чего не хватило в ответе и над чем поработать к следующему разу. Первые 30 минут бесплатно.