✔️ Мой чеклист и рекомендации по документированию аналитических приложений с помощью dbt Docs


🟢 Источники данных - заполните максимум для себя и тех кто будет изучать документацию

Примерный список атрибутов:

— Source (Mobile Apps Events)
— Type (JSON files)
— Way of data integration (S3 table engine)
— Description (Events tracked in Mobile Apps, single file for each event)

🟡Структурирование проекта на слои преобразований

Мой пример:
— Sources
— Staging
— Intermediate
— Analytics (dims / facts)

🔵Цветовая схема на графе dbt Docs

Ноды dbt (включая модели) можно окрасить в разные цвета на графе:

    staging:
      +docs:
        node_color: "#219EBC"

🔴Скрыть нерелевантные модели из документации

models:
  <resource-path>:
    +docs:
      show: true | false

🟤Блоки {{ doc() }}: Переиспользование блоков документации

В целом, большие блоки документации стоит вынести в отдельные markdown-файлы. Возможно, с картинками и схеми.

Также имеет смысл один раз описать атрибут (колонку), который присутствует в 1+ моделях, и впоследствие ссылаться на его описание:

models:
  - name: events
    description: '{{ doc("table_events") }}'

🩷Custom overview page - главная страница сайта с документацией

Рекомендую грамотно использовать title page и разместить на нем самую важную информацию:

— Используемые инструменты и сервисы
— Архитектурная схема
— Описание источников данных
— Ссылки на JIRA (task trackers), Wiki pages, Operational systems, Contacts (@), etc.

{% docs __overview__ %}

## OVERVIEW
## INFRASTRUCTURE SCHEMA
## TOOLS USED
## DATA SOURCES
## USEFUL LINKS

{% enddocs %}

🟢Публикация вебсайта

Т.к. сайт статический, его достаточно разместить в Object Storage с поддержкой Static website hosting:

— Host on Amazon S3 (optionally with IP access restrictions)
— Publish with Netlify
— Use your own web server like Apache/Nginx

🟡Актуализация вебсайта с документацией - всегда Up to Date

Чтобы вебсайт всегда отражал актуальное состояние, необходимо после каждого изменения в код (Merge Request), генерировать и загружать новую версию.

Делать это можно с помощью Github Actions или аналогов, автоматизируя действия:

— dbt docs generate
— aws s3 sync ./target s3://my-website-bucket/

🌐 @data_apps | Навигация по каналу