1. Documention¶

You can find the video summary for this section here

1.1. Overview¶

Good documentation helps yourself, your team, and business individuals to understand reporting datasets.

Per dbt, “dbt provides a way to generate documentation for your dbt project and render it as a website. The documentation for your project includes:

Information about your project: including model code, a DAG of your project, any tests you’ve added to a column, and more.
Information about your data warehouse: including column data types, and table sizes. This information is generated by running queries against the information schema.” - source

With all that being said, maybe this will convince you

“Documentation is a love letter to your future self” - Damian Conway

In the next steps, we will create our dbt documentation site, as seen in the following example:

Example #0

1.2. Table Metadata w/.yml files¶

First, we create a yml file mart_schema.yml to store our table metadata for our documentation.

Example #1

Here is a snippet of the file:

version: 2

models:
    
  - name: household_demographics_dim
    columns:
      - name: hd_demo_sk
        description: "Blah"
      - name: hd_income_band_sk
        description: "Blah"
      - name: hd_buy_potential
        description: "Blah"
      - name: hd_dep_count
        description: "Blah"
      - name: hd_dep_count
        description: "Blah"
      - name: hd_vehicle_count
        description: "Blah"
      - name: income_band_bound
        description: "Blah"
  - name: customers_dim
    meta:
      contains_pii: true

Note: Additionally, one can add metadata, tests, or other attributes to our yml file configuration, as part of the great dbt features offered to analysts. You can find our more in dbt’s resources.

1.3. Adding Overview information¶

Now, though we have our Metadata attributes for our specified tables, there is no necessary (welcoming) Overview in our table. To add such an overview for our materialized tables, we create a seperate markdown .md file to create our respective overviews.

For example, let’s check out how to add an overview to table catalog_sales_monthly_fct

Note: It’s important to add Jinja template statements {% %} surrounding your documentation, in the markdown file

{% docs catalog_sales_monthly_fct %}

# Catalog Sales (Monthly Totals)

This table contains Catalog Sales events from our transactions source for Catalog Sales.

......................

{% enddocs %}

1.4. Generate and Present your website¶

The following commands will help you generate your dbt docs, assuming there are no configuration issues with either your .yml file or .md file.

dbt docs generate
dbt docs serve

Note: If you have a serve issue to a particular port, try adding the flag --port ####

From the above, we observe the overview & metadata attributes are added to our datasets! Now individuals will be able to do some further data discovery into identifying what the purpose of both the tables and associated columns are!

1.5. Misc.¶

There are some additional items that could be added to our dbt docs, like having an overview section, and more!

For more information about dbt docs, you can find it here.

And again,