Design Docs: когда писать, а когда пропустить
Команда из восьми инженеров, которую я консультировал в прошлом году, держала правило: любой тикет больше 3 story points требует design doc. Получалось около четырёх документов в неделю, по полдня на написание и ещё полдня на циклы ревью. Итого 32 инженерных часа в неделю — четыре полных рабочих дня на документы, которые большинство людей пробегало глазами один раз и больше не открывало. CTO считал, что у них высокая дисциплина. Данные говорили, что у них перегруз документации и провал по velocity.
Обратная крайность ещё хуже. Stack Overflow Developer Survey 2019 года назвал «плохую документацию внутренних систем» блокером продуктивности №2 — сразу после технического долга. Полностью отказаться от design docs значит, что каждый рефакторинг через полгода превращается в археологические раскопки.
Это фреймворк, которым я пользуюсь, чтобы решить: какие изменения заслуживают документа, какие — комментария на 3 предложения в RFC, а какие — ничего.

