Сколько времени тратить на документацию?

Пятнадцать-двадцать минут на новый отчёт: паспорт и запись в словарь. Дальше это окупается первым же вопросом коллеги, который вы не разбираете заново.

Что делать, если в команде документацию не ведут?

Начните со своих расчётов и не пытайтесь переделать всех: словарь по трём ключевым метрикам и паспорта по двум главным отчётам уже дают эффект. Остальные подтянутся, когда увидят, что вопросы перестали повторяться.

Как описать чужой отчёт, который достался по наследству?

Начните с восстановления расчёта: прогоните запросы, сверьте с известными числами, выпишите источники и фильтры. Описание делайте по факту, а не по догадкам, и помечайте, что осталось непроверенным.

Нужно ли писать документацию на английском?

Зависит от команды. Главное — единый язык в словаре метрик: если названия метрик на английском, описания тоже, иначе появится путаница в терминах.

Что делать с устаревшими отчётами?

Не удаляйте сразу: сначала пометьте датой остановки и причиной, затем предупредите тех, кто ими пользовался. Через месяц, если вопросов нет, можно архивировать.

Документация аналитика: что вести и как хранить

Зачем это вам, а не начальнику

Через полгода вы не вспомните, почему в отчёте исключены заказы дороже ста тысяч и откуда взялся период в тринадцать месяцев. Без записи придётся поднимать переписку, лезть в историю правок и всё равно сомневаться.

Вторая причина — вопросы от коллег. Один и тот же вопрос «а почему тут так» приходит трижды, и каждый раз это полчаса. Записанный ответ экономит эти полчаса всем.

Третья — вы сами меняете расчёт по просьбе заказчика. Если изменения не записаны, никто не узнает, что сравнивать прошлый месяц с текущим нельзя.

Ответ на вопрос «откуда это число» без переписки.
Один раз записали — трижды не объясняли.
Видно, когда расчёт менялся и почему.

Три документа, которые закрывают почти всё

Не пытайтесь описать всё. Начните с трёх вещей: словарь метрик, паспорт отчёта и журнал изменений. Этого хватает, чтобы разобраться в любом числе.

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

Словарь метрик: смысл, формула, источник, владелец.
Паспорт отчёта: назначение, аудитория, частота, ограничения.
Журнал изменений: дата, автор, что и зачем поменяли.

Словарь метрик

На каждую метрику хватит пяти строк: название, что означает для бизнеса, формула словами, источник данных и владелец. Отдельной строкой — ограничения: чего метрика не показывает.

Если метрику считают двумя способами, это надо записать: например, выручка по дате заказа и по дате оплаты. Оба варианта верны для своих задач, и без записи спор бесконечен.

Формулу пишите словами, а не только кодом: «доля заказов, оплаченных в течение суток после оформления» понятно всем, а запрос на сто строк — не всем.

Название и смысл: какое решение обслуживает метрика.
Формула словами и ссылка на расчёт.
Источник, владелец и ограничения.

Паспорт отчёта или дашборда

Паспорт отвечает на вопросы, которые задают в первую очередь: для кого отчёт, как часто обновляется, откуда берутся данные, что делать при расхождении с другим отчётом.

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

Укажите контакт владельца и дату последней проверки: отчёт, который никто не обновлял год, вызывает меньше доверия, чем свежий.

Назначение и аудитория: какие решения принимают по отчёту.
Источники, частота обновления, задержки.
Известные проблемы и что делать при расхождении.

Как описывать запросы и пайплайны

Комментарий «считаем выручку» бесполезен: он повторяет код. Полезно другое — почему выбрана такая логика: «берём последнюю версию заказа, потому что заказы правятся после оформления».

Пишите в начале файла короткий блок: что делает расчёт, какие таблицы читает, от чего зависит запуск, куда пишет результат. Этого достаточно, чтобы через месяц разобраться.

Схему пайплайна держите рядом с текстом: стрелки и подписи источников понятнее трёх абзацев.

Пишем «почему так», а не «что делает строка».
В начале файла: назначение, источники, зависимости, результат.
Схема потока данных рядом с описанием.

Правила, при которых документацию читают

Коротко: страница, которую можно прочитать за две минуты, используется, а простыня на десять экранов — нет. Делите на небольшие страницы по темам и ссылайтесь между ними.

Одно место для одного ответа. Если правила метрики описаны и в вики, и в комментариях к коду, они разойдутся. Выберите главное место и отовсюду ссылайтесь на него.

У каждой страницы должны быть автор и дата изменения. Это не бюрократия: по дате видно, можно ли опираться на описание.

Примеры и скриншоты работают лучше определений: один пример расчёта объясняет больше, чем абзац терминов.

Короткие страницы по темам вместо одного длинного документа.
Один ответ живёт в одном месте, остальные ссылаются.
Автор, дата изменения, пример или скриншот.

Где хранить

Для расчётов и пайплайнов удобно держать описание рядом с кодом: тогда правка кода и правка описания попадают в один набор изменений, и расхождение видно сразу.

Для соглашений, словаря метрик и паспортов отчётов подойдёт вики или общий документ: туда ходят не только аналитики.

Не заводите третье место «на всякий случай»: два хранилища — уже много, три — гарантированный хаос.

Код и пайплайны — рядом с кодом в репозитории.
Соглашения и словарь — в вики или общем документе.
Ссылки между местами вместо копий текста.

Что делать при расхождении

Когда числа не сходятся, не удаляйте старую версию расчёта молча. Запишите, в чём было расхождение, какая версия верна и с какой даты. Через месяц этот вопрос придёт снова.

Отдельно фиксируйте изменения, которые ломают сравнение: новый фильтр тестовых аккаунтов, смена источника, исправленная логика дублей. Иначе рост на графике примут за рост продукта.

Если расхождение с отчётом финансов, договоритесь о правиле сверки: например, ежемесячно сверяем выручку по дате оплаты. Правило важнее разового объяснения.

Старую версию не удаляем, а помечаем датой и причиной.
Отдельно отмечаем изменения, ломающие сравнение периодов.
Одно правило сверки с финансами.

Что сделать: короткий чеклист

Завёл словарь метрик: смысл, формула, источник, владелец.
Описал паспорт отчёта с назначением и ограничениями.
Веду журнал изменений: дата, автор, причина.
В расчётах пишу «почему так», а не пересказ кода.
У каждой страницы есть автор и дата изменения.
Один ответ живёт в одном месте, остальные ссылаются.
Отмечаю изменения, после которых нельзя сравнивать периоды.
Есть правило сверки с отчётом финансов.

Где тренировать

Темы из гайда разобраны в тестах портала — каждый вопрос с объяснением ответа:

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

Как вести документацию аналитика