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