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