This hub covers the dbt documentation style guide: why consistency matters, what to put in model and column descriptions, the technical mechanics of writing descriptions in dbt, enforcement tooling, and rollout strategy.
Prerequisites
You should be comfortable with basic dbt YAML structure (schema files, models: blocks, columns: blocks). Knowledge of dbt’s three-layer architecture helps for understanding which documentation standards apply at which layer.
Reading Order
Start with the argument for why this matters:
- dbt Documentation Style Guide Rationale — why inconsistency is the root problem, and why style guides now serve AI tools as well as humans
Then the writing patterns: 2. dbt Model Description Writing Patterns — the four-question framework for model descriptions, column description patterns, source descriptions, and the description-vs-meta distinction 3. dbt Description YAML Formatting Options — inline strings, folded scalars, literal scalars, and doc blocks: when to use each YAML format
Then the reuse mechanics: 4. dbt Doc Block Syntax and Reuse Patterns — how doc blocks work, naming conventions, where they pay off first 5. dbt Doc Block File Organization — per-directory, per-model, centralized, and hybrid approaches 6. dbt Doc Block Jinja Limitations — what you can’t do inside doc blocks and the README parsing gotcha
Then enforcement: 7. dbt Documentation CI Enforcement — dbt-checkpoint pre-commit hooks, dbt-score quality scoring, and graduated enforcement by folder 8. dbt Project Evaluator for Documentation — dbt-project-evaluator for materializing coverage as queryable models 9. dbt Documentation Scaffolding Tools — dbt-codegen for generating YAML skeletons, dbt-osmosis for propagating descriptions through lineage
Finally, the rollout: 10. dbt Documentation Rollout Strategy — week-by-week approach for embedding documentation standards without a big-bang sprint