Рукописи не горят? Подборка о составлении документации

“Если мы посчитаем количество строк кода, то стоит рассматривать их не как “произведённые строки”, а как “строки потраченные”, - это же можно применить и к документации, на мой взгляд.

Недавно мы записали выпуск подкаста о документации и о том, почему её так часто игнорируют. Я готовилась: перечитала статьи, пересмотрела доклады. Поняла, что некоторые статьи тоже хочется игнорировать 😊 Списку пришлось подождать своего часа и он наконец дождался. Делюсь с вами - вдруг пригодится.

🔖 Статьи:
Плохое ТЗ — это не вина одного человека. Это результат работы команды Авторы пояснили - это статья про то, что требования должны перестать жить только в тексте. Речь о том, как собрать вокруг модели бизнес, разработку и тестирование, чтобы находить противоречия до начала кода, а не после. Спойлер: не обошлось без ИИ.

«Кто на ком стоял?» Про страдательный залог в технической документации Давняя статья, о том как штампы и канцеляризмы из других текстов въедаются в стиль, которым пишут аналитики.

Нужно ли команде тратить время на ревью требований? (peer-to-peer review) В этом посте три причины, почему ревью полезно даже тогда, когда кажется, что всё и так понятно.

Требования vs Реальность: Почему в ТЗ находят «дыры» и как это исправить Здесь акцент именно на способы передачи информации, а не на выяснение проблем. Если честно, в этой статье мне почему-то не захотелось нажать на добавку кармы на Хабре, тем не менее есть вполне реалистичные примеры неполных требований и рекомендации по составлению документа ТЗ.

Как работает шаблон документа? Пост о том, что не все шаблоны одинаково полезны, содержит подборку статей с шаблонами.

Поиск по бизнес-процессам: почему ваши регламенты никто не читает Если путь к процессу длиннее, чем вопрос в чат, люди перестают искать, модели устаревают, а доверие к базе падает. В статье — о том, почему иерархия папок не работает, как семантический поиск сокращает путь от вопроса до ответа.

🎥 Доклады:
Доклад Сергея Нужненко на WAW 2025 “Как писать, чтобы покороче, но со всеми важными деталями“

Доклад Сергея Нужненко на Flow 2023 “Ловушки проектирования и как с ними бороться“

Иннокентий Бодров "Сожгите ваши системные требования. Пользовательские требования — ключ к успешному продукту"

Максим Корейченко, Иннокентий Бодров "Как описать задачу разработчикам, чтобы они не считали тебя идиотом"

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

#что_почитать