ROI документации: когда писать, когда пропустить

Сеньорный инженер у fintech-клиента потратил 3.5 часа на runbook для процесса деплоя, который она надеялась никогда не запускать вручную. Через 8 месяцев это спасло джуна на on-call примерно 4 часа в 2 часа ночи на банковском выходном. Дока дала аккуратный возврат в 15% времени. Соседняя дока той же недели — 6-страничный архитектурный обзор системы, которую выводят из прода — по логам вики не открывалась ни разу. Та же команда, те же часы, радикально разный ROI.

Документация не бесплатна и не бесконечно ценна. Инженерный разговор обычно формулируется как «нам нужно больше доков» или «доки всегда устаревают» — оба утверждения одновременно верны, это и есть подсказка. Настоящий вопрос: какие доки окупаются, как быстро, и когда писать хуже, чем признать, что знание неявное. Это фреймворк, чтобы решать до потраченных часов.

{/* truncate */}

Проблема: доки имеют цену, и она не ноль

Вдумчивая дока — 2-8 часов сеньорного времени. При fully-loaded rate $120k/год — $120-500 на доку. Умножьте на 30 инженеров, пишущих по 5-10 в год, — $18-150k в год только на документации. Стоимость невидима в большинстве бюджетов, потому что идёт из инженерного времени.

Write Docs Day Foundation, опрос практиков 2024 (Valentine Reid, lead author): медианная enterprise-дока имеет read-to-write ratio 4.2 — каждую доку читают чуть больше 4 раз до устаревания. Это не 4× ROI, это сырое число открытий. Большинство прочтений — skim-and-close; реальный коэффициент «передано информации» ниже. Не все доки одинаковы: тот же опрос — runbooks в среднем 11 чтений, архитектурные доки 1.8 чтения до устаревания. Тема предсказывает ценность сильнее качества.

Пятишаговое решение. Большинство споров «надо ли писать?» пропускают шаг 3 (стоимость написания) и 4 (стоимость устаревания).

Три класса документации (разная экономика)

Класс A — Runbooks и операционные доки. Высокий reuse, конкретная ценность на чтение. Экономит часы в инцидентах. Лучший ROI.

Класс B — Архитектурные и design docs. Средний reuse, высокая ценность за чтение, когда консультируются. Часто перепроизводятся относительно реального потребления.

Класс C — Процессные и onboarding. Burst-ное переиспользование (новички бьются в месяц 1, дальше редко). Хороший ROI при лаконичности.

Failure mode: команды вкладывают Class B усилие (8-часовые архитектурные дайвы) на задачу Class A (30-минутный runbook). Хуже — Class B усилие на системах, которые депрекейтнутся за 12 месяцев, и дока мертва до прочтения.

Конкретная формула ROI

Для предлагаемой доки считайте:

ROI = (ожидаемые_чтения × часов_экономии_за_чтение) / (стоимость_написания + стоимость_поддержки)

Где:

• ожидаемые_чтения — сколько раз откроют за 18 месяцев (реально, не надеясь)
• часов_экономии_за_чтение — экономия vs разобраться по коду / спросить коллегу (типично: 0.25-2 часа)
• стоимость_написания — часы сеньора, чтобы написать нормально
• стоимость_поддержки — часы в квартал на свежесть × кварталы полезности

Пример A — Deploy runbook:

• Ожидаемые чтения: 20 за 18 месяцев
• Экономия за чтение: 1.5 часа
• Написать: 3 часа
• Поддержка: 0.5 ч/кв × 6 = 3 часа
• ROI = (20 × 1.5) / (3 + 3) = 5.0 — писать

Пример B — Архитектурная дока депрекейтимой системы:

• Ожидаемые чтения: 3
• Экономия за чтение: 2 часа
• Написать: 8 часов
• Поддержка: 1 ч/кв × 2 = 2 часа
• ROI = (3 × 2) / (8 + 2) = 0.6 — пропустить или отложить

Пример C — Onboarding-гайд для нового фреймворка:

• Ожидаемые чтения: 15 (новички + кросс-команды)
• Экономия за чтение: 0.5 часа
• Написать: 4 часа
• Поддержка: 0.5 ч/кв × 4 = 2 часа
• ROI = (15 × 0.5) / (4 + 2) = 1.25 — маргинально; писать только если нет проще альтернативы

Порог: ROI > 2.0 — писать. ROI 1.0-2.0 — рассмотреть альтернативы (README, inline comment, Loom-видео). ROI < 1.0 — пропустить.

Decay cost — вот что все недооценивают

Доки — не write-once. Неподдерживаемая дока становится активно вредной за 6-18 месяцев — новички ей доверяют, следуют сломанным инструкциям и сжигают больше времени, чем без доки. GitLab, постмортем 2023 (частично опубликован): 37% «как мне …» внутренних поисков возвращали доку старше 18 месяцев, и примерно четверть из них содержали хотя бы одну материально неверную инструкцию.

Оценка расхода на поддержку по классам:

Класс	Поддержка/квартал	Горизонт устаревания
Runbook (operational)	0.5-1 ч	6 мес при изменении системы
Architecture	1-2 ч	12 мес
Onboarding	0.5 ч	6 мес для тулинга, 12 для процесса
Reference (API, config)	Автогенерить или не писать	Устаревает быстрее всего; автогенерация

Инсайт: reference-доки (API, config) почти никогда не писать руками. Автогенерировать из кода/схемы; рукописный слой — только «почему» поверх. Команда, пишущая и поддерживающая API reference руками, накапливает decay без апсайда против генерации.

4-шаговый pre-write чек

Перед посвящением полдня доке спросите:

1. Кто это прочитает и когда?

• Конкретные роли (on-call инженер, новичок backend, PM на интервью)
• Конкретные триггеры (во время инцидента, в onboarding, в design review)
• Если ответ «кто-нибудь, когда-нибудь» — пропустить или радикально сжать.

2. Какая альтернативная стоимость без неё?

• Вопрос в Slack, на который отвечают за 5 минут — ок.
• Вопрос в Slack, пингующий трёх сеньоров и разваливающий фичу — не ок.
• Дока окупается против альтернативы, не против нуля.

3. Можно ли заменить 5-строчным README или Loom-видео?

• README.md в корне репо бьёт 5-страничный вики в 80% случаев.
• 10-минутный Loom бьёт рукописный onboarding для визуальных процессов.
• «Лучший» формат — тот с наименьшим трением, который читатель реально использует.

4. Кто владелец?

• Дока без именованного владельца стареет в бесполезность за год.
• Если честно «я напишу, и никто не будет поддерживать» — пропустить.

Готовая политика «писать vs пропустить»

Copy-paste policy для любой команды:

Писать:

• Любая процедура, теряющая знание с уходом одного человека
• Любой инцидент-runbook для системы с >3 on-call инженерами
• Любая onboarding-дока, где одинаковый вопрос задают 5+ раз
• Любое архитектурное решение, по которому будут спрашивать через 6 месяцев («почему мы выбрали X?»)

Не писать:

• Всё, что можно автогенерить из кода или схемы
• Любое объяснение, переписываемое на каждый релиз
• «Comprehensive guide» по системе, которая уйдёт за 18 месяцев
• Любая дока, где ответ «просто прочитай код», а кода <200 строк

Типовые ошибки

• Class B усилие на Class A проблему. «Напишу comprehensive архитектурный обзор» там, где хватило бы двухабзацного runbook.
• Нет именованного владельца. Общая дока — ничья дока. Именованный владелец с квартальным ревью — самая предсказательная переменная свежести.
• Писать вместо починить. «Эта система запутана, напишу доку» — часто сама система сломана; дока замазывает настоящий fix.
• Дубликаты. Три страницы «Staging Auth» в трёх местах. Хуже, чем без доки, — читатель не может доверять ни одной.
• Доки как performance theater. Писать, чтобы показать усилие, не чтобы передать знание. Видно по reads-per-doc.

Как мерить, окупаются ли инвестиции в доки

Три числа, которые ваш вики-инструмент почти наверняка даёт, но вы не смотрели:

Метрика	Здорово	Внимание
Доки, прочитанные ≥3× за 90 дней после создания	>60%	<40%
Медианный возраст самых читаемых доков	<12 мес	>18 мес
Time-to-first-answer для новичков (заранее согласованные 10 вопросов)	Падает	Флэт или растёт

Подробнее про это писали в knowledge management comparison — выбор инструмента значит меньше, чем дисциплина владения. Time-to-first-answer — самая сигнальная метрика, которую большинство команд не меряет.

Где вписывается PanDev Metrics

Три применения:

Корреляция ramp онбординга. Мы меряем time-to-meaningful-PR во время онбординга разработчиков. Команды с лучше поддерживаемыми доками показывают на 20-30% быстрее ramp при той же сложности кодовой базы. Это измеримо.

Атрибуция времени на доки. Наша IDE-heartbeat данные разделяют coding time и не-coding (редактор, браузер, тулинг). Технические тексты в Markdown показываются как «coding-like» активность — можем оценить, сколько часов команда тратит на доки в месяц и сравнить с числами чтений.

Сигнал устаревания из code churn. Если модуль меняется еженедельно, а связанная дока не редактировалась 9 месяцев, дока скорее всего устарела. Мы можем поверхностить «likely-stale» списки, коррелируя code churn с last-edited timestamps доков.

Соседствует с широким вопросом стоимости в cost per feature — доки часть скрытой cost envelope, которую большинство команд не учитывает.

Честный лимит

Наши данные видят код и IDE-активность; внутрь вики или Confluence не видят. Числа читабельности — из публичного ресёрча Write Docs Day Foundation, постмортема GitLab и трёх наших клиентов, добровольно поделившихся wiki-аналитикой для валидации фреймворка. У нас нет статистически robust выборки по read-to-write; фреймворк направленно честен, не утверждение точности.

Второй лимит: ROI-формулы дают ложную точность. Ожидаемые чтения — догадка, не число. Ценность формулы — в том, что заставляет команду артикулировать предположение, не что даёт надёжный балл.

Самый жёсткий тезис

Документация — инженерная стоимость, заслуживающая того же ROI-анализа, что любая другая инвестиция. Команды, пишущие рефлекторно («надо это задокументировать»), накапливают устаревание быстрее, чем ценность. Команды, пишущие селективно («эту доку откроют 20 раз и сэкономят 30 часов»), строят компаундящийся актив. Разница за 3 года не маленькая; это вопрос, является ли ваш вики инструментом или кладбищем.

По теме

• Knowledge Management для dev-команд — дополняющее сравнение инструментов
• Ramp онбординга разработчика — где хорошие доки окупаются нагляднее всего
• Cost Per Feature: расчёт инженерного ROI — широкий фреймворк атрибуции стоимости
• Внешнее: GitLab Handbook — docs-as-code на масштабе, публично доступно
• Внешнее: Write the Docs Community — практические исследования экономики документации