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 includingcatalog.json,manifest.json, and HTML docsdbt 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