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