15 апреля 2026 г.

Как писать data documentation

Зачем документация

Без документации

  • Новый analyst тратит 2 месяца, чтобы понять, где что.
  • Каждый считает метрики по-своему.
  • «Почему DAU в этом дашборде 100k, а в другом 90k?»
  • Когда ведущий аналитик уходит — unknown unknowns.

С документацией

  • Onboarding сокращается в 2–3 раза.
  • Single source of truth для метрик.
  • Дебаг проблем быстрее.
  • Trust to data в компании.

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

1. Таблицы и колонки

Что хранится, откуда берётся, что значит.

2. Метрики

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

3. Pipeline-ы

Как данные попадают в DWH.

4. Dashboards

Что показывают, для кого, как обновляются.

5. Процессы

Как ранить эксперимент, как добавить метрику.

6. Decisions и ADRs

Почему сделали именно так.

1. Документация таблиц

Что включать

table: orders

description: Заказы пользователей в продакшне

source: Postgres production DB (replica)

refresh: Every hour

primary_key: order_id

foreign_keys:
  - user_id → users.user_id
  - product_id → products.product_id

columns:
  order_id:
    type: uuid
    description: Уникальный идентификатор заказа
    example: '123e4567-e89b-12d3-a456-426614174000'

  user_id:
    type: uuid
    description: ID пользователя
    nullable: false

  amount:
    type: numeric
    description: Сумма заказа в копейках
    example: 100000  # ₽1000
    notes: В копейках, не рублях!

  status:
    type: varchar
    description: Статус заказа
    values:
      - draft: В создании
      - pending: Ожидает оплаты
      - paid: Оплачен
      - refunded: Возврат
      - cancelled: Отменён

  created_at:
    type: timestamptz
    description: Время создания в UTC

usage_tips:
  - Для revenue используй только status = 'paid'
  - Refunded остаётся в таблице, amount не обнуляется
  - Часовой пояс — всегда UTC, конвертируй для дашбордов

2. Документация метрик

Формат

metric: daily_gmv

definition: >
  Суммарная выручка за день по всем заказам
  со статусом 'paid', исключая returns.

formula: |
  SUM(amount)
  FROM orders
  WHERE status = 'paid'
    AND DATE(created_at) = report_date

granularity: day

dimensions:
  - region
  - platform
  - product_category

owner: product_analytics_team

refresh_schedule: Daily at 02:00 UTC

related_metrics:
  - weekly_gmv
  - monthly_gmv
  - gmv_per_active_user

notes:
  - Валюта всегда RUB.
  - Refunded не вычитается.
  - Если нужно net — см. net_gmv

3. Документация pipeline-а

Шаблон

# Pipeline: daily_user_metrics

## Описание
Ежедневно считает базовые продуктовые метрики: DAU, WAU, MAU,
new users, retention D1/D7/D30.

## Источники
- `events` (ClickHouse) — основной источник
- `users` (Postgres, replicated to CH)

## Schedule
Каждый день в 03:00 UTC.



## Owner
@tagir (product_analytics)


Попробовать силы на подобных вопросах проще всего в [тренажёре Карьерник](https://t.me/kariernik_bot/app?startapp=web_blog_kak-pisat-data-documentation_mid1) — прямо в Telegram, без регистрации через сайт.

## Steps
1. Extract: `events` за last 30 days
2. Transform: aggregate в daily_user_metrics_staging
3. Load: upsert в `mart_user_metrics_daily`
4. Quality check: %NULL < 1%, row count > 100k

## Runbook
### Pipeline упал
1. Проверить Airflow logs
2. Проверить статус ClickHouse
3. Если данные неполные — restart с параметром backfill

### Данные подозрительные
1. Сравнить с source tables (raw events count)
2. Проверить changelog ETL

4. Документация дашбордов

Что включать

  • Что показывает.
  • Для кого (audience).
  • Как обновляется.
  • Какой период.
  • Как интерпретировать.
  • Кто owner.
# Dashboard: Product Health

**URL:** tableau.company.com/dashboards/product-health

**Audience:** PMs, Head of Product, CEO

**Refresh:** Daily at 04:00 UTC

**Data range:** Last 90 days, some widgets 12 months

## Widgets

### NSM (Weekly Active Buyers)
- Main metric
- Red: below 400k
- Yellow: 400-500k
- Green: 500k+

### Retention Cohorts
- Weekly cohorts last 12 weeks
- Hover to see % retention

## Owner
@tagir

Где хранить

1. dbt docs (для таблиц и моделей)

Автоматически генерируется из dbt-моделей:

models:
  - name: fct_orders
    description: "Fact table orders"
    columns:
      - name: order_id
        description: "Unique order ID"

dbt docs generate && dbt docs serve → готовая wiki.

2. Confluence / Notion / Wiki

Для процессов, runbooks, architecture decisions.

3. Data Catalog

Enterprise решения: DataHub, Amundsen, Alation, Atlan.

4. README в Git

Для пайплайнов, SQL-кода.

Формат и структура

Consistent template

# [Метрика / Таблица / Pipeline имя]

## Определение
Одним предложением.



## Деталь
5–20 строк.


Пройти 30–50 задач по теме за вечер можно в [Telegram-тренажёре](https://t.me/kariernik_bot/app?startapp=web_blog_kak-pisat-data-documentation_mid2). Это то, что отличает «знаю» от «уверенно отвечу на собесе».

## Примеры
Конкретные примеры использования.

## Связанное
Ссылки на related.

## Owner
Кто отвечает.

## Last updated
Дата.

Один шаблон = легче писать и читать.

Разбиение на разделы

Крупные документы бьём на:

  • Tables.
  • Metrics.
  • Pipelines.
  • Dashboards.
  • Processes.

Не один большой файл.

Процесс документирования

1. Начать с главного

Первые 20 таблиц + 20 метрик — критичные.

2. Писать по мере создания

Новая таблица / метрика / дашборд — сразу docs. Не «потом».

3. Review process

PR на новую docs-page → apps. Не «пиши что хочешь».

4. Обновления

Квартально review всех pages. Удалить устаревшие, обновить.

5. Automation

Где можно — auto-gen из кода / dbt / БД.

Антипаттерны

1. «Документация — позже»

Никогда не «позже». Всегда at the time.

2. Слишком подробно

«Это поле создаётся когда пользователь кликает на...» — 3 страницы. TLDR, пожалуйста.

3. Слишком кратко

«user_id» — какого пользователя? PK ли? Откуда берётся?

4. Устаревшая

Бесполезная. Хуже, чем отсутствие — даёт ложные ожидания.

5. Не findable

Если никто не найдёт — не документировано.

Ownership

Без owner — документация гниёт:

  • Кто пишет initial.
  • Кто обновляет.
  • Кто ответственный за quality.

Обычно: тот, кто делает таблицу / метрику / pipeline — owner docs.

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

FAQ

Сколько времени уходит?

10-15% рабочего времени на написание / поддержку.

Кто отвечает?

Каждый аналитик — за свои таблицы / метрики. Head — за общие процессы.

Confluence или dbt docs?

Оба. dbt — для технических (таблицы). Confluence — для процессов.

Что, если никто не читает?

Проблема doc-а: либо не нужно, либо не findable, либо устарело. Исследуйте.

Тренироваться в Telegram