dbt Docs is an automatically generated HTML documentation site describing every model, source, column, macro, and test in the dbt project. It is generated from YAML metadata in `schema.yml` files and the compiled SQL of each model. Running `dbt docs generate` produces a `catalog.json` file; `dbt docs serve` renders the documentation site. The result is a self-updating data catalogue that stays in sync with the codebase — if a column is added and documented in `schema.yml`, the docs reflect it on the next generation run without any manual documentation maintenance.
The most valuable feature of dbt Docs is the lineage graph: an interactive visualisation showing every model and source as a node, with directed edges representing `ref()` and `source()` dependencies. Clicking any node expands its dependencies and dependents; the full graph shows the complete data flow from raw sources through staging to marts. This visual lineage is the primary tool for impact analysis — selecting a column in a staging model reveals every mart model and dashboard that would be affected by a change to that column.
Analogy🏏Cricket
🏏 Think of it like cricket: Migrating from Airflow to Prefect is like the same bowling coach shifting from traditional Test cricket notation to a modern T20 analytics dashboard — the underlying ball-by-ball data (the business logic) is exactly the same. What changes is how the data is recorded, displayed, and acted upon. The yorker that Bumrah bowls in over 20 is identical whether it is recorded in the old scorebook (Airflow DAG file) or the new analytics platform (Prefect flow). The migration is a transcription exercise, not a strategy change — and a wise coach verifies that the runs, wickets, and economies match exactly between the old and new system before decommissioning the scorebook. That verification step is the whole heart of the migration: because the yorker is unchanged, the only honest test is to run the same over through both systems and confirm the recorded runs, wickets and economies match to the last digit before the old scorebook is thrown away. Rushing to burn the scorebook the moment the shiny dashboard lights up is how teams lose a season of records to a silent transcription slip. The coach keeps both systems running in parallel for a while, reconciles their outputs ball by ball, and only when every figure agrees does he trust the new dashboard alone — a transcription is only complete when you have proven nothing was lost in the copying.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.