Documentation best practice

In-Depth Discussions
1

Hello,

We are a squad of 6 people who eventually will be mentaining a cluster of about 100 models in dbt.

I would like each of these to have two things clearly documented. Just around 1-2 sentece for each.

  1. Purpose - This model is doing XX
  2. Granularity

This information is only inteded to be used by the members in our squad when doing further development to the models. Noone else then our squad are using the models we create. (We pick them up ourselves in a BI tool)

  1. Do you think this fits best as a simple SQL comment at the top of each model?
  2. Or is it better to use the description function in the schema.yml connected to the model?

1 feels nice since you have the information right there when you open the model. 2 feels more correct, and if we ever want to share the information we can just use dbt docs.