Сегодня хочу затронуть холиварную тему.

В одном лагере — Agile-манифест: «работающий продукт важнее исчерпывающей документации».

В другом — Amazon с их принципом: «каждое решение должно быть документировано».

Спор длится годами. И у каждого есть свои святые.

Но есть нюанс, который часто упускают.

Я видел, как документация спасала проекты: от тяжёлых заказчиков, от смены команды, а однажды — даже от суда.

И видел, как она же их топила, когда её пихали туда, где она не нужна.

КАК ПОНЯТЬ, КОГДА ОНА НУЖНА? Записывай, если решение: ▸ влияет на архитектуру ▸ выходит за границы оговорённых усилий ▸ создаёт прецедент для будущих задач Всё остальное — в чёрный ящик.

КАК ЗАПИСЫВАТЬ, ЧТОБЫ НЕ УТОНУТЬ? Золотой стандарт — три строки: 1. Что выбрали 2. От чего отказались 3. Почему

«От чего отказались» — самая важная строка. Именно она даёт контекст, почему выбрали не самое очевидное решение.

Для сложных ситуаций — метод «5W+H» (Кто? Что? Когда? Где? Почему? Как?). Он даёт полную картину, когда трёх строк уже недостаточно.

Главное — фиксировать не только «что», но и «почему». Без этого контекст теряется. И через полгода вы тратите часы на созвон, чтобы вспомнить: «А почему мы, блин, выбрали этот путь?».

Документация — это не бюрократия. Это ускорение.

▸ Это когда новый человек выходит на полную мощность за день, а не за две недели. ▸ Это когда через полгода вы не тратите время на восстановление контекста.

Как только вы находите эту грань — проект перестаёт быть войной с документацией и становится работой с контекстом.

А где в ваших проектах эта грань?