dbt Docs: Steps and Usage

dbt not only allows you to transform data in its warehouse but also lets you generate documentation for your models with just a few commands. It also turns that documentation into a beautiful website for user-friendly access. In this tutorial, we’ll walk you through everything about dbt Docs — its benefits, structure, and how to create one. Let’s dive in!

What is dbt Docs?

Think of dbt Docs as the user manual for your dbt project — automatically generated and easy to explore. It generates an interactive website that displays how your data models connect and data flows between them, making it easier for users to explore the project.

In simple terms, instead of digging through SQL files, your team gets a clear, clickable map of your entire data transformation process. It’s like having a well-organized blueprint that explains your entire data transformation process, making your work more accessible to both technical and non-technical team members.

Why dbt docs?

Good documentation for your dbt models improves the adaptability and clarity across teams. Let’s break down how documentation helps your work scale.

Improves communication among the stakeholders

First, it improves communication. By turning your dbt project into a visual and searchable website, you help users understand what’s going on with the data. This way, developers no longer need to explain how everything works. 

Makes the project easy to maintain, understand, and troubleshoot

It also makes the project easier to maintain and troubleshoot. When something breaks or needs to be updated, you can quickly debug it, as we have clear model descriptions. That means it is easier to trace issues, update logic, and understand dependencies.

Speeds up onboarding for new team members

New hires don’t have to go through SQL code or ask others for help. They can use dbt Docs to explore models and understand how data flows quickly. This fastens and simplifies the onboarding process significantly. 

Acts as a self-service portal to answer common data questions

Business users no longer depend on IT staff to understand dbt models. They can look it up in the docs and use them on their own, minimizing dependency and speeding up the process. 

How data build tools integrate code and Documentation:

Generally, code and documentation are kept separate. dbt breaks the “code vs. docs” barrier by bringing them together in one place.

Instead of keeping documentation separate, dbt automatically pulls key details — model names, columns, sources — from your project and incorporates them into the docs. This keeps everything in sync, reducing manual updates and making it easier for your team to maintain the project. No more juggling between code and documentation — it’s all right there.

How to add Documentation

dbt lets you add custom documentation. There are two main ways to do this:

Add descriptions in YAML files:

You can write short descriptions of models, columns, and sources in your yaml file. These descriptions will appear on the dbt Docs site when you execute the code. This helps others to understand what your project does.

Example:

models:
    - name: employee
      description: "This model contains employee details such as personal info."
columns:
    - name: emp_id
      description: "A unique identifier for each employee."
    - name: emp_name
      description: "The employee's name."
    - name: department
      description: "The department where the employee works."
    - name: hire_date
      description: "The date the employee joined the company."

In the above example, we described the model name and explained what it represents.

We also added descriptions to the columns (emp_id, emp_name, department, hire_date) to clarify what each one means. You can follow the same approach to document sources as well.

Use doc blocks:

Another way to add documentation in dbt is through doc blocks.

Doc blocks are text blocks that can be placed in a Markdown (. md) file in your dbt model folder as long as you need to include longer descriptions, formatted text, or simply reusable documentation blocks. You define a doc block in a Markdown file using special tags. You can reference the doc block in your model file.

Example:

Create a Markdown file (employee_info.md)

{% docs employee_info %}

This model contains detailed information about employees, including their department, job role, and hire date.

Use this model to analyze employee distribution by department and track hiring trends.

{% enddocs %}

This model includes information about employees, such as department, job title, and date of hire. You can use the above model to see how employees are distributed by department, and to follow hiring trends. 

dbt docs commands

To create and view the dbt documentation, you will primarily use two commands: 

dbt docs generate and dbt docs serve.

dbt docs generate

This command gathers all your documentation (descriptions from YAML files, doc blocks from Markdown files, and metadata from your data warehouse) together and constructs a complete documentation site. It prepares everything dbt Docs needs to display your project in a structured & readable form.

dbt docs serve

Once you’ve generated the documentation, this command will launch a local web server. You and your team can then open up the docs in a browser, browse the models, view the relationships, and generally explore them. This is an easy way to move docs around so all people on the project have access.

Key Sections in the dbt Docs Interface

Project Section

This section shows all the dbt project—level objects – models, sources, seeds, snapshots, and tests. This displays the location of the files in your project folder in your project search engine.

Database Section

This view shows the objects that exist in your data warehouse (tables or views created by dbt), it helps you understand how your models are materialized and what schema they live in within your warehouse, and helps you understand the warehouse level impact of your project.

Search Box

The search bar at the top is useful when you’re looking for something specific, like what table, column, or model it is you want, to rapidly find the information you’re looking for without having to scroll through folders by hand.

Linear Graph 

One of the most popular uses and features of dbt Docs is the data lineage graph. This lets you see how data flows across models — from data sources to outputs. You can also look at upstream and downstream dependencies to help you debug or get an idea of how changing something will impact the rest of the pipeline.

Conclusion

dbt docs is an excellent tool for making your data workflows more transparent, clear, and efficient. Use dbt Docs to turn your dbt project into an interactive documentation site that is easily searchable and can help both technical and non-technical team members understand the data traffic through your models.

With capabilities such as YAML-based descriptions, doc blocks, a searchable interface, and data lineage graphs, dbt Docs makes your project easier to explore, maintain, and explain. It’s to help make your dbt project a documented, understandable project for everyone who worked on it.

Want to take your dbt transformations to the next level? Try Hevo Transformer, which is built on dbt Core to simplify, schedule, and scale your transformations with ease.

Frequently Asked Questions