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