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