Introduction

In dbt, there are two ways to document your models. The first and easiest way is to do so inside the .yml file like in one of the acoustic form subtables below:

Documentation

The other, more sustainable and scalable method is through use of the jinja docs tag. You may have seen this in the structure of the subtables’ schema yml files.

Using the schema_pitfall_trap_sublayer_survey yml file as an example, the objectid, globalid and date_time_details descriptions have been declared using the doc function like so:

Doc function

Setting up the descriptions

The markdown files

All documentation for our dbt work will be found within the docs folder. Inside this folder, there are other subfolders with each subfolder having one or more markdown (.md) files for each particular Survey123 form. Apart from the subfolders, there are two key markdown (.md) files: the 1) overview.md and the references.md file.

overview.md

This contains the ‘overview’ page of Natural State within the dbt documentation. Consider this as the homepage of Natural State. The overview page is a special page and needs some special syntax.

Docs overview

Overview example

Custom overview

references.md

This is the file containing documentation for all the field names. Name any field name, eg objectid, sample_qr_code, x and the like and its description will be found inside the references.md file. We use the jinja tag docs to enclose the description for any field.

References

The descriptions enclosed inside the docs tag are what will be referenced by the doc function from within our schema yml files. For example, the description for object id will be referenced by doc(“objectid”).

If all goes well, the description will appear in the deployed dbt website like so:

Description

Form specific subtable descriptions

As earlier mentioned, every form consists of sublayer and/or subtables. For example, the pitfall trap consists 5 subtables. For each subtable, it is also prudent to provide a description for it as this is what external stakeholders will first read before delving into the field descriptions.

For example, if you go to the src/docs/pitfall-trap folder, you will get the pitfall_trap_ref.md. Inside this markdown, we have placed the descriptions for all of our five subtable schema files of: 1) schema_pitfall_trap_sublayer_survey.yml, 2)schema_pitfall_trap_sublayer_grid_location_repeat_deploy.yml, 3)schema_pitfall_trap_sublayer_grid_location_repeat_retrieve.yml, 4)schema_pitfall_trap_subtable_repeat_deploy.yml and 5) schema_pitfall_trap_subtable_repeat_retrieve.yml. If some subtables are similar in nature, such as those for repeats in the Survey123 form, the descriptions can be reused as we’ve done so for this form.

Subtable descriptions