Why Documenting models in YAML in dbt? - Purpose & Use Cases

The Big Idea

What if your project's documentation could update itself perfectly every time you change a model?

The Scenario

Imagine you have many data models in your project, and you try to keep notes about each model in separate text files or scattered spreadsheets.

When someone new joins, they have to hunt through all these places to understand what each model does.

The Problem

This manual way is slow and confusing.

Notes get outdated or lost, and it's easy to make mistakes when updating documentation separately from the models.

It's hard to keep everything consistent and clear for everyone on the team.

The Solution

Documenting models in YAML lets you write clear, organized descriptions right alongside your data models.

YAML files are easy to read and update, and dbt uses them to automatically generate up-to-date documentation.

This keeps your docs and models in sync, saving time and avoiding errors.

Before vs After

✗ Before

# In separate text file
ModelA: This model calculates sales totals.
ModelB: This model filters active customers.

✓ After

models:
  - name: ModelA
    description: "Calculates sales totals."
  - name: ModelB
    description: "Filters active customers."

What It Enables

You can easily share clear, accurate model documentation that updates automatically as your project grows.

Real Life Example

A data analyst joins your team and quickly understands each model's purpose by reading the generated docs from YAML, without asking for explanations.

Key Takeaways

Manual notes are scattered and hard to maintain.

YAML documentation keeps descriptions close to models and easy to update.

dbt uses YAML docs to create clear, consistent project documentation.