03. Generating Documentation
What Is dbt Documentation?
dbt allows you to generate interactive documentation for your entire project, including:
- Models and their descriptions
- Column-level documentation
- Data lineage (graph view)
- Tests and exposures
This is a powerful feature that turns your dbt project into self-service documentation for analysts and developers.
Steps to Generate dbt Docs
Step 1: Add Descriptions
Ensure your models, sources, and columns are documented in schema.yml:
models:
- name: orders
description: "Stores order details and customer info"
columns:
- name: order_id
description: "Unique ID for the order"
Step 2: Build Documentation
Run the following command:
dbt docs generate
This creates a target/manifest.json and catalog.json, which contain all metadata for your project.
Step 3: Serve the Documentation
To open an interactive web UI:
dbt docs serve
This will: Start a local server Open your interactive documentation site in the browser Show model lineage, dependencies, and details
Key Features of dbt Docs UI
Searchable documentation Graph view for model lineage Clickable models with descriptions and columns Includes sources, tests, exposures, and metrics
Best Practices for Generating Docs
Document as you develop to avoid missing info Use Markdown formatting in descriptions Include business context, not just technical details Regenerate docs after major changes
Example Command Workflow
# Build your project
dbt run
# Test your models
dbt test
# Generate docs
dbt docs generate
# Serve docs locally
dbt docs serve
Benefits of dbt Docs
Improves collaboration between engineers and analysts Acts as a single source of truth for your data models Enables self-service analytics