altimateai/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

6. Generate Docs

dbt docs generate
dbt docs serve  # Optional: preview locally

Documentation Patterns

Note: These are default templates. Always adapt to match project's existing style.

Model Description Template

description: |
  [One sentence: what this model contains]

  **Grain:** [What does one row represent?]

  **Business Rules:**
  - [Key rule 1]
  - [Key rule 2]

  **Caveats:**
  - [Important limitation or edge case]

Column Description Patterns

| Column Type | Documentation Focus | |-------------|---------------------| | Primary key | Source system, uniqueness guarantee | | Foreign key | What it joins to, NULL handling | | Metric | Calculation formula, units, exclusions | | Date | Timezone, what event it represents | | Status/Category | All possible values, business meaning | | Boolean/Flag | What true/false means in business terms |

Documenting Calculated Fields

- name: gross_margin
  description: |
    Gross margin percentage.
    Calculation: (revenue - cogs) / revenue * 100
    NULL when revenue = 0 to avoid division by zero

Anti-Patterns

• Adding documentation without checking existing project patterns
• Using different formatting style than existing documentation
• Describing WHAT (e.g., "The order ID") instead of WHY/context
• Missing grain documentation
• Not documenting NULL handling
• Leaving columns undocumented
• Copy-pasting column names as descriptions