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 **...