Прямой ответ
Документация живёт, когда её мало и она на своих местах. Четыре типа по Дивио — каждый отвечает на свой вопрос: обучение (tutorial — «сделай первый шаг»), how-to (рецепты задач — «как задеплоить», «как добавить миграцию»), reference (справочник API — генерируется из кода, руками не пишется — Sphinx/MkDocs), объяснения (почему устроено так — контекст и решения). Главный инструмент команды-разработчика — ADR (Architecture Decision Record): короткий файл «решение X: контекст / варианты / решение / последствия» на каждое значимое решение (выбор БД, паттерна, отказ от альтернативы) — ADR не устаревают по построению (фиксируют решение на момент принятия со статусом superseded при пересмотре — история мышления команды, которой нет больше нигде); без них «почему здесь Redis, а не Postgres-очередь» через год восстанавливается археологией или не восстанавливается — и решение принимается заново или нарушается вслепую. Практические правила против гниения: документация рядом с кодом (в репозитории, ревьюится вместе с диффом — отдельная вики-база расходится с реальностью за месяцы), минимальный набор на проект (README с запуском за 5 минут + how-to на частые операции + ADR-папка — этого достаточно малой команде), и правило касания: правя область, поправь и её документацию (как правило бойскаута для кода); устаревшая документация хуже отсутствующей — она actively обманывает.
ADR: формат и дисциплина
Шаблон (MADR/Nygard-классика): номер и заголовок («ADR-007: очередь задач — Celery с Redis-брокером»), статус (proposed/accepted/superseded by ADR-012), контекст (что за задача, какие ограничения — «нужны фоновые задачи, команда знает Python, инфраструктура — один Redis»), варианты (что рассматривали — Celery/RQ/свои воркеры — с аргументами «за/против» каждого), решение (что выбрали и почему именно это), последствия (что получили и чем заплатили — «Redis-брокер: проще, но без гарантий доставки RabbitMQ — приняли для некритичных задач — гарантии»). Дисциплина: ADR пишется в момент решения (часть PR/задачи, ревьюится — ревью-практика), не «потом по памяти»; пересмотр решения — новый ADR со ссылкой (старый в superseded — история не переписывается); порог записи — решения, которые дорого отменить (технологии, контракты, схемы данных — не каждый выбор переменной); и чтение — обязательная часть онбординга (десяток ADR объясняют проект лучше любой вики — «почему так» важнее «что есть»). Ценность проявляется в кризис: спор «надо было X» решается открытием ADR — либо контекст изменился (новый ADR), либо аргументы тех лет всё ещё в силе (спор закрыт за минуту).
README и how-to: вход и рецепты
README — контракт «за пять минут»: что это (два предложения), быстрый старт (клонировать → установить → запустить — команды копируются и работают; неработающий старт — первое, что отпугивает и новичка команды, и внешнего пользователя), ссылки на остальную документацию (не попытка вместить всё); для библиотек — установка/минимальный пример/ссылки на reference. How-to guides — рецепты конкретных задач, ориентированные на цель («как добавить новую миграцию», «как выкатить хотфикс», «как подключить нового потребителя к топику» — Kafka-сценарии — кандидаты на how-to); формат — шаги-команды-ожидаемый результат, без теории (теория — в объяснениях/ADR); источник лучших how-to — повторённые вопросы в чате команды (вопрос прозвучал дважды — ответ становится гайдом). Докстринги — reference-слой в коде: модуль/класс/функция публичного API — что делает, параметры, возврат, исключения, пример (не «пересказ сигнатуры» — def add(a, b): """Складывает a и b""" — шум; ценность — контракт и неочевидное: побочные эффекты, потокобезопасность, единицы измерения); внутренние функции — по необходимости (сложное — да, тривиальное — нет); генерация справочника — Sphinx/mkdocs из докстрингов (инструменты) — reference не ведётся руками дважды.
Диаграммы как код и защита от гниения
Диаграммы в draw.io-экспортах гниют мгновенно (картинку не обновишь в PR вместе с кодом) — практика: диаграмма как код (Mermaid/PlantUML текстом в Markdown — версионируется, ревьюится в диффе, рендерится на лету; последовательность операций, схема сервисов, ER — три частых типа) — «диаграмма устарела» лечится тем же правилом касания в PR. Защита всей документации от расхождения с кодом: тестируемость (стартовые команды README прогоняются в CI на чистом контейнере — «документация работает» буквально; how-to с командами — кандидаты на скрипты-проверки), минимализм (меньше текста — меньше поверхности устаревания; дублирование информации в двух местах — гарантированное расхождение — один источник + ссылка), владение (CODEOWNERS на доки-каталоги — у документации есть ответственные, как у кода), и удаление (мёртвые гайды удаляются — «пусть лежит» обманывает читателей; история — в git). Реалистичная оценка для малой команды: README + ADR + 5–10 how-to + докстринги публичного API — 95% пользы документации при 20% усилий «полной документации всего»; остальное дописывается по мере появления вопросов (документация по требованию — живая, заранее — мёртвая).
Практический сценарий: документация проекта за две недели
Контекст: проекту два года, документация — README с устаревшим стартом и вики-страница «настройка» (половина команд не работает); онбординг новичка — неделя вопросов в личке. План: (1) README переписан и проверен на чистом клоне (CI-джоба «docs smoke»: контейнер, команды старта, healthcheck — старт не может сгнить молча); (2) ADR-ретро: пять археологических раскопок по «почему так» (выбор Postgres, отказ от микросервисов, схема очередей, формат событий, auth-подход) — пять ADR задним числом, помеченные «зафиксировано постфактум» — база для будущих; (3) how-to из чат-логов: топ-8 вопросов стали гайдами (миграция, деплой, локальный стенд, добавление эндпоинта, отладка очередей...); (4) докстринги — только публичный API двух общих библиотек (внутреннее — не трогали); (5) правило в DoD: PR, меняющий поведение/процесс, правит связанные how-to/ADR (ревьюер проверяет — часть чек-листа). Итоги: следующий онбординг — два дня вместо недели (новичок шёл по README+how-to, вопросы — только действительно новые); ADR-006 предотвратил повторное «давайте перепишем на микросервисы» (контекст двухлетней давности оказался в силе — обсуждение закрыто ссылкой); docs-smoke в CI дважды поймал сломанный старт после изменений зависимостей — документация буквально тестируется. Объём — ~20 страниц на проект; «полная документация» так и не писалась — не понадобилась.
FAQ
Комментарии в коде или докстринги — что документировать где? Докстринг — контракт (что/параметры/возврат/исключения — для вызывающего); комментарии — «почему здесь так» (нестандартный обход, причина костыля со ссылкой на ADR/issue — для правящего); пересказ кода комментарием — шум в обоих местах; правило: код отвечает «что делает», комментарий — «почему именно так», докстринг — «как этим пользоваться».
Нужна ли вики (Confluence/Notion) при доках в репо? Для процессного/организационного (встречи, планы, онбординг-чек-листы нетехнические) — удобна; для технической документации кода — нет (расхождение с кодом, нет ревью в диффе, поиск в двух местах); техника живёт в репо, вики ссылается на неё, не дублирует.
Кто пишет ADR — автор решения или техписатель? Автор решения (он владеет контекстом и аргументами; техписатель может причесать форму позже); ADR, написанный не участником решения, — пересказ без нюансов; формат-шаблон снижает порог — полчаса на запись в момент решения — инвестиция в будущие споры и онбординг.
Как документировать API для внешних пользователей? Reference генерируется из контрактов (OpenAPI → Redoc/Swagger UI — контрактная разработка — документация и реализация из одного источника), поверх — how-to сценарии («авторизация», «первый запрос», «обработка ошибок» — версии API и changelog — часть документации) и интерактивные примеры; автогенерация без сценариев — справочник без входа, сценарии без справочника — гайды без полноты.
Источники: adr.github.io, Divio documentation system, Sphinx docs — ссылки в шапке.