In this lesson, you will learn how to write structured YAML documentation to transform your dbt models into a searchable catalog for your team.
When your data warehouse grows to hundreds of models, even the most diligent data engineer can forget what a specific column represents. While dbt run builds your tables, the documentation site acts as the "map" that helps others find and understand your data. By documenting your models, you move away from tribal knowledge toward a self-service data culture.
The Power of YAML Documentation
In dbt, we define our documentation within schema.yml files. By adding descriptions to your models and columns, you provide context that dbt automatically renders into a clean, searchable web interface.
Consider this example for a stg_orders model:
version: 2
models:
- name: stg_orders
description: "Contains cleaned order data, filtered for active customers only."
columns:
- name: order_id
description: "Primary key for the order. Unique identifier."
- name: order_status
description: "The current state of the order (e.g., 'shipped', 'pending', 'returned')."
- name: order_date
description: "The date the order was placed in UTC."
Why This Matters for Discoverability
When a business analyst searches the dbt documentation site for "order status," they will now find exactly where that data originates and what the values mean. Without these descriptions, stakeholders have to dig through complex SQL files just to figure out what a column signifies.
By writing these definitions, you bridge the gap between technical implementation and business utility. It turns your dbt project into a living dictionary that integrates seamlessly with your lineage graphs, allowing team members to trace a column's journey from raw source to finished dashboard with total clarity. Once the YAML is written, you simply run dbt docs generate to update your interactive site.
Key Takeaway: Descriptive YAML documentation turns your codebase into a self-service knowledge base, ensuring your data is not just functional, but also discoverable and understandable for your entire organization.