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.** ```bash # 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 ```bash cat models/<path>/<model_name>.sql ``` Understand: transformations, business logic, joins, filters. ### 3. Check Existing Documentation for This Model ```bash # 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):** ```yaml 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 ```bash 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 ```yaml 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 ```yaml - 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