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