Design Docs: когда писать, а когда пропустить
Команда из восьми инженеров, которую я консультировал в прошлом году, держала правило: любой тикет больше 3 story points требует design doc. Получалось около четырёх документов в неделю, по полдня на написание и ещё полдня на циклы ревью. Итого 32 инженерных часа в неделю — четыре полных рабочих дня на документы, которые большинство людей пробегало глазами один раз и больше не открывало. CTO считал, что у них высокая дисциплина. Данные говорили, что у них перегруз документации и провал по velocity.
Обратная крайность ещё хуже. Stack Overflow Developer Survey 2019 года назвал «плохую документацию внутренних систем» блокером продуктивности №2 — сразу после технического долга. Полностью отказаться от design docs значит, что каждый рефакторинг через полгода превращается в археологические раскопки.
Это фреймворк, которым я пользуюсь, чтобы решить: какие изменения заслуживают документа, какие — комментария на 3 предложения в RFC, а какие — ничего.
{/* truncate */}
Проблема: документы, написанные не ради дела
Design docs проваливаются двумя путями, и оба избегаемы.
Провал 1: Документ как ритуал. Он существует, потому что процесс требует существования. После апрува никто его не открывает. Автор потратил полдня; ревьюеры — час календарного времени; артефакт принёс ноль ценности для принятия решения.
Провал 2: Не написан там, где был нужен. Что-то собрали, через полгода сломалось неочевидным образом, и на post-mortem спрашивают «почему это решение не задокументировано?». Сеньор, принимавший решение, уже ушёл. Логика утеряна. Перестройка стоит 3x от первоначального усилия.
Engineering-practices guide от Google формулирует цель прямо: design doc существует, чтобы вытащить разногласия на поверхность до того, как появится код, потому что цена разногласия на этапе дизайна — минуты, а на этапе code review — дни. Если ваш документ не вытаскивает разногласия, вы либо написали его слишком поздно, либо он не был нужен.
Академические данные это подтверждают, но с оговорками. Ernst et al. (2015), Measure It? Manage It? Ignore It? в IEEE Software, обнаружили, что команды, пишущие целевые design docs, релизят с 20-30% меньшим количеством пост-релизных дефектов, чем команды со стихийной документацией — но только когда документ фиксировал tradeoffs, а не переописывал код. Документ, повторяющий содержимое PR, хуже, чем отсутствие документа: он добавляет календарное трение без добавления обоснования.
Фреймворк из трёх вопросов
Три вопроса, три исхода. Большинство изменений уходят в «пропустить» или «RFC-комментарий». Полноценный документ нужен меньшинству.
Вопрос 1: Объём работы больше 1 инженер-недели?
Если один инженер доделывает изменение за неделю, обычно разумнее просто собрать его и дать описанию PR нести контекст. Описание PR — это лёгкий design doc со 100% прочтения, потому что ревьюер физически не может замержить, не открыв его.
Порог в неделю не случаен. Работа дольше недели почти всегда пересекает границы модулей, и как только границы пересечены, у разных людей появляются мнения про интерфейс. Вот тут письменная форма становится дешевле обсуждений.
Вопрос 2: Изменение затрагивает больше одной команды?
Кросс-командные изменения требуют документа независимо от объёма. Даже миграция схемы на полдня, которая трогает два сервиса, нуждается в однастраничном design doc, потому что две команды не встретятся раньше PR, а PR — неподходящая площадка для споров об интерфейсе.
Однокомандные изменения — даже большие — часто решаются в общем /rfcs/ канале или ветке pull request. Круг ревьюеров маленький и уже делит контекст, так что длинный письменный артефакт приносит убывающую отдачу.
Вопрос 3: Изменение обратимо в пределах одного рабочего дня?
Это тест «радиуса поражения», заимствованный из SRE-практик. Если откат занимает у одного инженера один день, описывайте постфактум, а не до. Если откат займёт неделю или физически невозможен (миграция схемы, изменение публичного API, смена формата данных), решение стоит того часа, который уйдёт на написание.
«Обратимо за день» — удобная эвристика, потому что она чисто ложится на MTTR-данные. В командах, которые мы измеряли, средний деплой восстанавливается меньше чем за 4 часа, когда у изменения есть понятный путь отката. Изменения без пути отката — это те, что доминируют в MTTR, и именно их стоит документировать.
Матрица решения
| Объём > 1 недели | Кросс-команда | Обратимо за день | Что делать |
|---|---|---|---|
| Нет | Нет | Да | Пропустить — ship с нормальным описанием PR |
| Нет | Нет | Нет | Короткий RFC-комментарий (200-400 слов) |
| Нет | Да | Любое | 1-страничный design doc |
| Да | Нет | Да | RFC-тред в общем канале |
| Да | Да | Любое | Полный design doc, обязательно |
| Да | Нет | Нет | Полный design doc, обязательно |
Шесть комбинаций, три письменных исхода. Матрица не пускает команду в режим «документ на каждый тикет» и не пускает в режим «документов нет никогда».
Анатомия design doc, который реально используют
Документ, который переоткрывают через полгода, состоит из пяти секций — и никаких больше. Всё сверх пяти — это место, где прячется slop.
1. Контекст (3-5 предложений)
Что спровоцировало работу. Тикет, инцидент, стратегическая цель. Один абзац. Если длиннее — заголовок тикета уже делает эту работу за вас.
2. Решение (1-3 буллета)
Что мы собираемся собрать, сказано плоско. Не «рассматриваемые варианты». Решение. Варианты живут в секции 4.
3. Почему это, а не альтернативы (сердце документа)
Два-три рассмотренных варианта, к каждому — один абзац, почему отклонён. Это единственная секция, оправдывающая существование документа. Если не можете назвать альтернатив, вы не исследовали пространство, и документ преждевременен.
4. Риски и план отката
Что может пойти не так. Как откатимся. Если откат — «revert коммита», так и напишите в 5 словах. Если откат — «миграция данных назад по 12-шаговому runbook», пишите runbook.
5. Открытые вопросы
Вопросы, на которые вы не смогли ответить в одиночку. Это единственная секция, которой ревьюеры действительно пользуются. Открытый вопрос — приглашение; закрытый — сигнал, что спросить надо было раньше.
Всё. Пять секций. Если в вашем шаблоне есть «критерии успеха», «влияние на пользователя» и «дальнейшая работа» — это ритуал, а не фиксация решения.
Типичные ошибки
| Ошибка | Почему это вредит | Как исправить |
|---|---|---|
| Документ написан, когда код уже наполовину готов | Ревью превращается в rubber-stamp — решение уже принято | Писать в момент подлинной неопределённости, а не после |
| Документ повторяет PR без нового обоснования | Добавляет календарное время, ноль ценности | Если описывает код — делайте это описанием PR |
| Документ с 20 «рассмотренными вариантами» | Театр анализа — реального ранжирования нет | Максимум 3 альтернативы, по одному жёсткому абзацу на отклонение |
| Документ в Google Doc, который никто не может найти | Знание испаряется за 6 месяцев | Хранить в репозитории под /docs/design/ или /rfcs/ — ищется grep'ом, проходит PR-ревью |
| Все апрувят, никто не ревьюит | Соц-апрув без давления решения | Требовать хотя бы одного именованного «ревьюера» с письменным комментарием |
Как понять, что это работает
Метрика — не «количество написанных design docs». Это vanity-счёт. Отслеживайте две вещи:
- Доля документов, переоткрытых хотя бы раз после апрува — если меньше 30%, документы не используются, их ставят «для галочки». Шаблон слишком тяжёлый или фильтр объёма слишком широкий.
- Частота rework'а после решения — как часто решение, принятое в design doc, пересматривается или отменяется в течение 90 дней. Меньше 15% — документ ловит ошибки дизайна; больше 30% — документ рубберстампит решения, которые должны были остаться в форме RFC.
В PanDev Metrics мы отслеживаем активность по файлам, связанным с тикетами, — когда инженер переключает IDE-фокус на файл, упомянутый в design doc, это сигнал, что документ работает. Если документ ни разу не посещали после мержа, он кандидат на удаление при следующей уборке. Это данные из IDE heartbeat-телеметрии, сопоставленные с Git и трекером.
Честное ограничение наших данных: мы видим события open файла и фокус IDE, но не видим, прочитал и понял ли инженер документ, или пролистал его за 30 секунд. Документ, который пролистали, не сильно лучше того, который не открывали. Качественный сигнал остаётся важным.
Контрарная позиция
Большинство инженерных блогов советуют писать больше design docs. Я советую писать меньше, короче и раньше.
Меньше — потому что ритуальная документация хуже отсутствующей: она тренирует инженеров относиться к документам как к накладным расходам, из-за чего пропускают те, что действительно важны. Короче — потому что 5-страничный документ находит 3 читателей, а 1-страничный — 10. Раньше — потому что документ, написанный посреди реализации, это политическое прикрытие, а не фиксация решения.
Если ваша команда в режиме «документируем всё», ослабляйте правила объёма, пока хотя бы одно изменение в спринте не остаётся без документа. Если в режиме «не документируем ничего» — начинайте с комбинации «кросс-команда + необратимо». Оба края лечатся одним и тем же фреймворком; разница лишь в том, куда подтягивать.
Когда этот фреймворк не подходит
В регулируемых средах — medtech, авионика, оборонка — обязательная документация часто перекрывает фильтр объёма. Обратимое за день изменение в FDA-регулируемой кодовой базе всё равно требует трассируемой записи решения. Фреймворк оптимизирован под B2B SaaS; если документ будет читать аудитор — пишите независимо от матрицы.
Исследовательские организации работают по другим правилам. Двухнедельный разведочный прототип не требует design doc; двухнедельный прототип, идущий в прод, — требует. Если результат — статья, то документ — это статья.
Похожие материалы
- CTO Dashboard: что показывать еженедельно — где метрики документации живут в представлении инженерного лидера
- MTTR: почему скорость восстановления важнее предотвращения всех инцидентов — тест «обратимости», использованный в вопросе 3
- Контекст-свитчинг убивает продуктивность — почему ритуальные документы бьют по focus time сильнее, чем помогают alignment
- Внешнее: Engineering Practices от Google — краткий референс по нормам code review и design doc