Skip to main content

03. Documentation Generation

Documentation Generation in dbt​

Generating documentation ensures that all models, sources, and tests are well-described, improving team collaboration and maintainability.
dbt provides auto-generated documentation with lineage and schema details.


1. Writing YAML Descriptions​

  • Document models, columns, sources, and tests in YAML files:
version: 2

models:
- name: fct_orders
description: "Fact table for customer orders"
columns:
- name: order_id
description: "Primary key for orders"
tests:
- unique
- not_null
- name: order_date
description: "Date when the order was placed"
  • Descriptions enhance dbt docs visualization

2. Generating Documentation​

  • Run the following commands to generate docs:
# Generate documentation
dbt docs generate

# Serve documentation locally
dbt docs serve
  • dbt docs generate → Creates static artifacts including catalog.json, manifest.json, and HTML docs
  • dbt docs serve → Opens an interactive UI to browse models, lineage, and metadata

3. Viewing Lineage​

  • Interactive lineage graphs show:
    • Sources → Intermediate models → Mart/Production models
    • Dependencies and relationships
  • Helps assess the impact of model changes

4. Best Practices​

Keep descriptions updated as models evolve
Document critical business logic and transformations
Include column-level tests for clarity
Use lineage graphs to plan changes and reviews
Integrate docs generation in CI/CD pipelines for up-to-date documentation