Документация, которую читают

Документация, которую читают

Плохая документация пересказывает код словами, устаревает за месяц и начинает врать. Врущая хуже отсутствующей.

Что писать стоит. Как запустить проект с нуля на чистой машине — экономит каждому новичку по два дня. Почему приняты решения: код показывает «как», но никогда «почему». Что мы обещаем соседним командам и в каком формате.

Что не стоит: описание каждой функции и пошаговые инструкции по интерфейсу, который меняется ежемесячно.

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

И привычка, которая окупается: объяснили новичку что-то устно — запишите. Следующий споткнётся о то же самое.

IT Ростов-на-Дону — t.me/rostov_it