dbt documentation coverage tracking

This note covers tools for tracking dbt documentation coverage over time. CI enforcement catches per-PR failures; trend tracking shows whether project-wide coverage is improving or eroding across runs.

dbt-coverage: The comparison workflow

dbt-coverage by Slido computes per-model and project-wide documentation percentages from your manifest.json and catalog.json:

dbt-coverage compute doc \
  --manifest target/manifest.json \
  --catalog target/catalog.json

The output shows which models are fully documented, which are partially documented, and the overall coverage percentage. This gives you a snapshot.

Comparing across runs

The real power is the compare command. Save the coverage output from your main branch, then compare it against each PR:

# On main branch (save as baseline)
dbt-coverage compute doc \
  --manifest target/manifest.json \
  --catalog target/catalog.json \
  > coverage-main.json

# On PR branch (compare against baseline)
dbt-coverage compare doc coverage-main.json coverage-pr.json

The compare command exits non-zero if coverage drops, making it a CI gate. But more importantly, with --cov-format markdown it generates a table you can post as a PR comment:

dbt-coverage compare doc coverage-main.json coverage-pr.json \
  --cov-format markdown

Reviewers see which models gained or lost documentation coverage in the change.

What dbt-coverage doesn’t tell you

dbt-coverage checks for non-empty descriptions, not quality. A column described as customer_id: "The ID of the customer" counts as documented. The tool answers “how much documentation exists?” not “is the documentation useful?” For quality, you need human review, AI review, or drift detection.

dbt-score: Composite quality scoring

dbt-score by Picnic Technologies takes a broader view. Instead of documentation alone, it assigns each model a composite quality score from 0 to 10 based on documentation, tests, and ownership metadata. Default rules check:

• has_description — model has a description
• columns_have_description — all columns have descriptions
• has_owner — model has an owner tag or meta field

The CI integration uses configurable thresholds:

[tool.dbt-score]
fail_project_under = 7.5
fail_any_item_under = 6.0

The project average must stay above 7.5; no single model may drop below 6.0. This allows temporary gaps on new models while preventing complete neglect.

When to use dbt-score over dbt-coverage

dbt-coverage answers a narrow question: what percentage of columns have descriptions? dbt-score answers a broader question: how well-maintained is each model overall? If documentation is your primary concern, dbt-coverage is simpler and more direct. If you want a single quality metric that includes documentation alongside testing and ownership, dbt-score reduces the number of separate checks in your CI pipeline.

Tracking trends over time

Whichever tool you choose, the numbers are most useful when tracked historically. A single coverage number is a snapshot. A series of coverage numbers over weeks or months reveals patterns:

• Gradual erosion (92% to 87% to 83%) suggests new models are being added without documentation faster than gaps are being filled. The process isn’t keeping up with growth.
• Sharp drops (92% to 78%) usually correspond to a large PR that added many models without documentation, or a refactor that split models without updating YAML.
• Steady improvement (65% to 70% to 75%) shows that scaffolding tools and enforcement are working.
• Plateau (85% for months) might mean the remaining undocumented models are legacy models nobody wants to touch, and you need a different approach (like AI generation) to close the gap.

Recording coverage data

The simplest approach: capture the coverage output from each CI run and store it somewhere queryable. Options include:

• A dedicated dbt model that snapshots dbt-project-evaluator coverage data
• A CI artifact that writes coverage to a spreadsheet or database
• A dashboard that reads CI pipeline outputs
• Even a Slack message from CI with the current coverage number, creating a searchable history

The mechanism matters less than the habit. Whatever gets you a time series of coverage numbers enables trend analysis.

dbt Cloud built-in coverage

dbt Cloud users get coverage tracking without additional setup. The Project Recommendations page displays documentation and test coverage percentages using dbt-project-evaluator rules under the hood. It won’t fail your CI pipeline, but it provides visibility into trends through the dbt Cloud UI.

For teams already on dbt Cloud, this is the lowest-friction starting point. You can always layer dbt-coverage or dbt-score into your CI pipeline later when you need automated enforcement alongside visibility.

Coverage targets

100% coverage with stale descriptions is worse than incomplete coverage with accurate descriptions. 80–90% coverage on mart models (the layer users query directly) with lighter coverage on staging and intermediate models is a reasonable target for most projects. Track the trend and focus remediation where coverage has the highest impact.