15 апреля 2026 г.

Как документировать dashboard

Зачем документировать

Дашборд без документации — это источник проблем. Через полгода никто не помнит, почему этот чарт именно такой, какой там формулой считается retention, откуда берутся цифры.

Документация решает:

  • Новички понимают дашборд без pinging автора.
  • Stakeholder доверяют числам, потому что видят методологию.
  • Через год, когда автор ушёл, знание остаётся.
  • При bug investigation быстрее находится source проблемы.

10 минут на документацию экономят часы позже.

Что документировать

Минимальный набор информации:

Название и описание. Что за дашборд, зачем он.

Audience. Для кого. CEO, PM, маркетинг?

Ключевые метрики. Их определения с формулами.

Источники данных. Какие таблицы, какие события.

Фильтры. Что делают, default значения.

Refresh schedule. Как часто обновляется.

Owner и контакты. Кто отвечает.

Known limitations. Что дашборд НЕ показывает.

Где хранить

Варианты:

Встроенные description полей в BI. Tableau, DataLens, Metabase имеют поля для описания дашборда и виджетов. Минимально нужно заполнить.

Confluence / Notion. Отдельная страница с описанием. Ссылка на неё — в описании дашборда.

README в git (если dashboard как code, например Looker). Полноценная документация рядом с кодом.

dbt docs. Если данные идут из dbt-моделей, документация к моделям автоматически покрывает метрики.

Лучше всего — комбинация. Краткое описание в BI, полное — в Confluence.

Шаблон страницы дашборда

# Weekly Product Health Dashboard

## Назначение

Еженедельный мониторинг ключевых продуктовых метрик для PM-команды.
Обновляется каждый понедельник в 9:00 MSK.

## Audience

- Product Managers (primary).
- Head of Product.
- Ежемесячно просматривается CEO.



## URL

https://bi.company.com/dashboards/product-health

## Owner

@tagir (analytics team).
Slack: #analytics-team
Email: analytics@company.com


Тренироваться на таких вопросах можно в [Telegram-боте Карьерник](https://t.me/kariernik_bot/app?startapp=web_blog_kak-dokumentirovat-dashboard_mid1) — там 1500+ задач с реальных собесов с разборами.

## Key Metrics

### Weekly Active Users (WAU)

Уникальные пользователи, совершившие event `app_open` в течение 7 дней
до конца отчётной недели.

SQL:
```sql
SELECT DATE_TRUNC('week', event_time)::date AS week,
    COUNT(DISTINCT user_id) AS wau
FROM events
WHERE event_name = 'app_open'
GROUP BY 1

Источник: events (ClickHouse).

D7 Retention

Доля новых пользователей, вернувшихся на 7-й день после регистрации.

Classic definition: user совершил app_open ровно в день N+7 (не в диапазоне).

Источник: user_events_daily (dbt model).

Filters

  • Date range: default — последние 12 недель.
  • Platform: iOS, Android, Web. Default — all.
  • Country: все страны. Default — Russia.

Data sources

  • events — основная таблица events (ClickHouse).
  • users — профили пользователей (PostgreSQL, replicated в CH).
  • dbt.user_events_daily — предагрегированная.

Refresh schedule

Airflow DAG product_metrics_daily запускается ежедневно в 07:00 UTC. Dashboard читает из dbt-моделей, обновлённых по окончании DAG.

Задержка данных: до 24 часов.

Known limitations

  • Не учитывает bots (фильтр по bot_flag включён).
  • Sub-5-минутные sessions не считаются «активными» (product policy).
  • Data до 2024-01-01 неполная (переход на новый трекер).

Changelog

  • 2026-04-10: Добавлен фильтр по country.
  • 2026-03-15: Изменена формула retention (с unbounded на classic).
  • 2026-01-05: Первая версия.



## Определения метрик — критично

Метрики должны быть described с формулой. Не просто «DAU», а конкретно, что считается:

Плохо: «Active users за день».

Хорошо: «Уникальные user_id с событием `session_start` и session_duration > 30 секунд за календарный день в timezone Europe/Moscow».

Такой уровень detail важен, потому что DAU может быть определён по-разному, и разные определения дают разные цифры.

## Какие вопросы должна отвечать документация

Представьте, что новый PM открывает дашборд. Какие у него вопросы?

- Что тут на каждом чарте?
- Какой period показан?
- Можно ли фильтровать по X?
- Откуда берутся данные?
- Как часто обновляется?
- Кого спросить, если что-то непонятно?
- Что нельзя делать через этот dashboard (чего он не умеет)?

Документация должна иметь ответы на все эти вопросы.


К слову, набить руку на таких кейсах удобно через [тренажёр в Telegram](https://t.me/kariernik_bot/app?startapp=web_blog_kak-dokumentirovat-dashboard_mid2) — разбирайте по 10 вопросов в день, через 2 недели тема становится рефлексом.

## Automation

Для больших экосистем с сотнями дашбордов manual documentation не scales. Решения:

**dbt + Metabase auto-sync**. Documentation from dbt автоматически подтягивается.

**Data catalog** (DataHub, Amundsen). Централизованный реестр со связями между таблицами, метриками и дашбордами.

**Tableau Metadata API**. Извлечение metadata для внешней wiki.

Для маленьких команд manual docs fine. Для enterprise — автоматизация.

## Версионирование

Дашборды меняются. Documentation должна меняться с ними.

Лучшая практика — changelog в document. «2026-04-10: добавили фильтр по country». Это историчность, которая помогает понять, почему цифры «раньше были другие».

Для serious проектов — хранить версии дашбордов в git (если BI поддерживает). Tableau, Looker имеют Version Control features.

## Типичные ошибки

**No docs at all**. Самая частая ошибка. «Потом сделаю» = «никогда».

**Outdated docs**. Раз написал, забыл. Каждое изменение должно обновлять docs.

**Слишком подробно**. 30 страниц для простого дашборда. Никто не прочитает.

**Не findable**. Доки есть, но в личном Notion автора. Никто не найдёт.

**Без контекста**. «Retention D7 — это D7». Спасибо, тавтология. Пояснять именно business meaning.

## Review процесс

Для team дашбордов:

**Before publishing**. Autor пишет documentation → peer review → публикация.

**Quarterly review**. Раз в квартал — обновление docs, проверка актуальности.

**On change**. Любое значимое изменение дашборда — update docs в том же PR.

## Для своих ad-hoc analyses

Даже для одноразовых анализов документация полезна. Минимум:

- Название.
- Дата.
- Цель.
- Data sources.
- Ключевые выводы.

Через год вы будете благодарны prior-self, когда кто-то спросит «а помнишь тот retention анализ?».

## Читайте также

- [Как писать data documentation](/blog/kak-pisat-data-documentation)
- [Дашборд для CEO](/blog/dashboard-dlya-ceo)
- [Дашборд для PM](/blog/dashboard-dlya-pm)
- [Как сделать dashboard в DataLens](/blog/kak-sdelat-dashboard-v-datalens)

## FAQ

### Кто должен писать docs?

Автор дашборда. Если дашборд общий, определите owner-а.

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

30-60 минут после создания. Обновления — 5-10 минут.

### В чём разница между description и documentation?

Description — 1-2 предложения в BI. Documentation — подробная страница с метриками, источниками, ограничениями.

### Confluence или Notion?

Любой, который команда использует для docs. Главное — findability.
Тренироваться в Telegram