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

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

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

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

Правило гигиены: документация живёт рядом с кодом и правится тем же изменением.

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

IT Новокузнецк — t.me/it_novokuznetsk