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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Где хранить

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

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

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

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

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

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

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

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

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

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

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

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

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

• Бизнес-аналитика: 119 вопросов с разбором
• Базы данных: 218 вопросов про хранилища и витрины
• SQL: 159 вопросов с разбором ответов
• Первая неделя работы аналитика: что делать
• Подписка: 590 ₽ в месяц, 3 990 ₽ в год

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

Частые вопросы