documenting-dbt-models

dbt Documentation

Document the WHY, not just the WHAT. Include grain, business rules, and caveats.

Workflow

1. Study Existing Documentation Patterns

CRITICAL: Match the project's documentation style before adding new docs.

# Find all schema.yml files with documentation
find . -name "schema.yml" | head -5

# Read well-documented models to learn patterns
cat models/marts/schema.yml | head -150
cat models/staging/schema.yml | head -150

Extract from existing documentation:

• Description length (brief vs detailed)
• Formatting style (plain text vs markdown with headers)
• Information included (grain? business rules? caveats?)
• Column description depth (all columns vs key columns)
• Use of meta tags or custom properties

2. Read Model SQL

cat models/<path>/<model_name>.sql

Understand: transformations, business logic, joins, filters.

3. Check Existing Documentation for This Model

# Find existing schema.yml
find . -name "schema.yml" -exec grep -l "<model_name>" {} \;

# Read existing docs
cat models/<path>/schema.yml | grep -A 100 "<model_name>"

4. Identify Documentation Needs

For each model, document:

• Model description: Purpose, grain, key business rules
• Column descriptions: Business meaning, not just data type

For each column, consider:

• What business concept does this represent?
• Are there any caveats or special values?
• What is the source of this data?

5. Write Documentation

Match the style discovered in step 1. Example format (adapt to project):

version: 2

models:
  - name: orders
    description: |
      Order transactions at the order line item grain.
      Each row represents one product in one order.

      **Business Rules:**
      - Revenue recognized on ship_date, not order_date
      - Cancelled orders excluded (status != 'cancelled')
      - Returns processed as negative line items

      **Grain:** One row per order_id + product_id combination

    columns:
      - name: order_id
        description: |
          Unique identifier for the order.
          Source: orders.id from Stripe webhook

      - name: customer_id
        description: |
          Foreign key to customers table.
          NULL for guest checkouts (pre-2023 only)

      - name: revenue
        description: |
          Net revenue for this line item in USD.
          Calculation: unit_price * quantity - discount_amount
          Excludes tax and shipping

      - name: order_status
        description: |
          Current status of the order.
          Values: pending, processing, shipped, delivered, cancelled, returned