(Или почему ваш глоссарий — лучший друг аналитика)
Введение: Зачем аналитику писать документацию?
Представьте: вы присоединились к новому проекту, а там — сотни таблиц в DWH, десятки ETL-процессов и ни одного описания, что куда и зачем. Как понять, где искать данные о конверсии? Какой параметр в таблице user_actions отвечает за оплату? Ответы на эти вопросы часто превращаются в квест с расспросами коллег и reverse engineering кода. Именно здесь документация становится спасательным кругом, но… только если она сделана правильно.
Из личного опыта: в одном из проектов мы потратили 3 месяца на реверс-инжиниринг legacy-системы из-за отсутствия документации. После этого я стал фанатом «докам-лайт» — минималистичных, но эффективных решений.
Проблемы, которые убивают проекты без документации
1. «Где тут правда?»: Путаница в терминах
Пример: В одном проекте «активный пользователь» определялся как:
✔ В мобильном приложении — заход за последние 7 дней.
✔ В веб-версии — заход за последние 30 дней.
✔ В отчете для маркетинга — любое действие за всё время.
Без глоссария аналитики тратили часы на согласование метрик.
2. «Кто это придумал?»: Потеря контекста
✔ Кейс: В DWH обнаружилась таблица finance_debug_2022. Оказалось, это временный срез для аудита, который забыли удалить. Без описания назначения таблицы её пытались использовать в расчётах KPI.
3. «Почему всё сломалось?»: Риски при смене команды
История: После ухода ключевого разработчика ETL-процесс встал. Новый сотрудник потратил 2 недели на изучение кода вместо доработки.
3 принципа «документации-лайт»
1. Реестр поделок (Artifact Registry)
Это таблица, где собраны все артефакты проекта с кратким описанием:
Зачем:
✔ Быстрый поиск нужного объекта.
✔ Избегание дублирования (перед созданием нового дашборда проверяем реестр).
2. Реестр метрик (Metric Catalog)
Пример структуры для метрики LTV:
✔ Формула: Сумма(доход_от_пользователя) / Количество_пользователей
✔ Источники данных: Таблицы payments, users.
✔ Ограничения: Не учитывает возвраты.
✔ Владелец: Петрова А.
Кейс: В проекте для e-commerce такой реестр сократил время на согласование отчетов на 40% 5.
3. Глоссарий (Data Dictionary)
✔ Правило: Каждый термин имеет одно определение.
✔ Пример:
«Сессия» = Непрерывная активность пользователя с интервалом не более 30 минут между действиями.
Лайфхак: Используйте формат Q&A для часто задаваемых вопросов:
✔ Вопрос: «Почему в отчете за март LTV ниже, чем в феврале?»
✔ Ответ: «Март включает тестовых пользователей из кампании Х, которые исключены из расчёта LTV (см. глоссарий, раздел «Метрики»)».
Инструменты: Как не утонуть в поддержке
1. Confluence + Excel: Для старта. Таблицы с реестрами и глоссарием хранятся в структурированных страницах.
2. Data Catalog (например, Apache Atlas): Автоматическое извлечение метаданных из DWH + ручное описание бизнес-контекста.
3. dbt + документация: Генерация описаний таблиц прямо из SQL-комментариев.
Важно: Документация должна обновляться в момент изменения данных. Добавили новое поле в таблицу? Сразу внесите его в реестр!
Когда документация вредит?
1. Перфекционизм: Попытки описать каждую таблицу до мелочей приводят к тому, что документация устаревает ещё до публикации.
2. Бюрократия: Требование согласования каждого изменения у 5 руководителей.
3. Отсутствие культуры: Если команда не видит ценности в документации, она становится «мёртвым грузом».
Совет из практики: Проводите ежемесячные «дни чистоты» — 1 час на актуализацию реестров.
Заключение: Документация как живой организм
Хорошая документация — это не толстая папка в Confluence, а инструмент коммуникации. Она должна:
✔ Быть легко обновляемой.
✔ Содержать только актуальную информацию.
✔ Решать конкретные проблемы команды.
Как сказал один мой коллега: «Документация — это как зубная нить: все знают, что она нужна, но мало кто регулярно её использует». Исправьте это в своей команде — начните с малого: реестра метрик и пяти строчек глоссария.
P.S. Если вы дочитали до конца — поздравляю! Теперь откройте ваш проект и проверьте, есть ли там описание таблицы finance_debug_2022 ;)