dbt Documentation

dbt generates a documentation website directly from your project files. The site includes a searchable list of all models, sources, seeds, and snapshots with their descriptions, column definitions, and a visual lineage graph. Good documentation means anyone on your team can understand what each table contains and where the data comes from without asking anyone.

Where Documentation Lives

Documentation comes from two places in your project:

Inline in YAML files

# models/staging/schema.yml
models:
  - name: stg_orders
    description: "One row per order. Cleaned from raw Shopify data."
    columns:
      - name: order_id
        description: "Primary key. Unique identifier for each order."
      - name: amount_dollars
        description: "Order total in USD. Converted from cents."

In doc blocks (for longer descriptions)

For descriptions longer than a few words, use doc blocks stored in .md files:

-- models/staging/staging.md
{% docs stg_orders %}
One row per order placed on the Shopify storefront.

Raw data arrives in cents. This model converts all monetary
fields to USD by dividing by 100.

Cancelled orders are excluded. Use stg_refunds for refund data.
{% enddocs %}

# schema.yml - reference the doc block
models:
  - name: stg_orders
    description: "{{ doc('stg_orders') }}"

Adding Model-Level Descriptions

version: 2

models:
  - name: fct_orders
    description: >
      Fact table containing one row per order.
      Joins orders, customers, and products.
      Used by the Revenue and Operations dashboards.

  - name: dim_customers
    description: >
      Customer dimension table.
      Contains current state of each customer record.
      Use customers_snapshot for historical state.

Adding Column Descriptions

models:
  - name: fct_orders
    columns:
      - name: order_id
        description: "Primary key. One row per order."
      - name: customer_name
        description: "Customer full name from the CRM at time of order."
      - name: amount_dollars
        description: "Order total in USD including tax and shipping."
      - name: is_completed
        description: "True if the order reached 'completed' status."
      - name: days_to_ship
        description: "Calendar days between order_date and ship_date."

Documenting Sources

sources:
  - name: ecommerce
    description: "Raw Shopify data synced via Fivetran. Refreshes every hour."
    tables:
      - name: orders
        description: "Raw order records from Shopify Admin API."
        loaded_at_field: _fivetran_synced
        columns:
          - name: id
            description: "Shopify order ID. Becomes order_id after staging."
          - name: financial_status
            description: "Payment status from Shopify."

Documenting Seeds

seeds:
  - name: country_codes
    description: "ISO 3166-1 alpha-2 codes with region groupings."
    columns:
      - name: code
        description: "Two-letter country code (e.g. US, IN, GB)."
      - name: region
        description: "Continent-level grouping for regional reporting."

Reusing Column Descriptions

If the same column appears in many models with the same meaning, you can define it once and reference it everywhere using the include mechanism or doc blocks:

-- docs/column_descriptions.md
{% docs order_id %}
Primary key for the orders table. Sourced from Shopify order ID.
Unique across all orders. Never reused for cancelled orders.
{% enddocs %}

{% docs customer_id %}
Foreign key to dim_customers. References the customer who placed the order.
{% enddocs %}

# Use in any model's YAML
columns:
  - name: order_id
    description: "{{ doc('order_id') }}"
  - name: customer_id
    description: "{{ doc('customer_id') }}"

Generating and Viewing Docs

# Step 1: Generate the documentation artifacts
dbt docs generate

# Step 2: Serve the documentation website locally
dbt docs serve

After running dbt docs serve, your browser opens to a local documentation site. The site includes:

• A searchable list of all models, sources, seeds, and snapshots
• Column-level descriptions and test results for each model
• A visual lineage graph showing upstream and downstream dependencies
• Source freshness status

The Lineage Graph

The lineage graph is one of dbt's most powerful documentation features. It shows every node in your DAG and how data flows between them:

[source: shopify.orders] ──> [stg_orders] ──> [fct_orders] ──> [report_revenue]
[source: crm.customers]  ──> [stg_customers] ──┘
                                                └──> [dim_customers]

Click any node in the graph to see its description, columns, tests, and direct dependencies. Use the focus feature to zoom in on one model and see only its immediate parents and children.

Documentation Best Practices

• Write a description for every model in the marts/ folder at minimum
• Always describe primary key and foreign key columns
• Note any business logic or data quality caveats in model descriptions
• Keep descriptions factual and brief — one to three sentences per model
• Use doc blocks for descriptions longer than two sentences