Документация, которую действительно читают
Плохая документация пересказывает код словами. Она устаревает за месяц и начинает врать, а врущая хуже отсутствующей.
Что писать стоит. Как запустить проект с нуля на чистой машине — это экономит каждому новичку по два дня. Почему приняты те или иные решения: код показывает «как», но никогда «почему». Что мы обещаем соседним командам и в каком формате.
Что писать не стоит: подробное описание каждой функции и пошаговые инструкции по интерфейсу, который меняется каждый месяц.
Правило гигиены: документация живёт рядом с кодом и правится в том же изменении.
И привычка, которая окупается: объяснили что-то новичку устно — запишите. Следующий споткнётся о то же самое.
IT Тверь — t.me/it_tver
IT Тверь
@it_tver