Add the ability to define a terms section or glossary

[datGnomeLife]

Describe the feature

With the introduction of exposures I think there is a great opportunity to expand on some more of the “meta data” capabilities in dbt docs. I think a great addition would be a terms glossary. This could be for business terms or some other terms that are often repeated. I think this could be best achieved with a new yaml schema, something to the effect of:

version: 2

terms:
  - name: Congestion Revenue Rights
    description: "a brief description or a more detailed one using doc blocks: {{ doc('link_to_doc') }}"
    meta: 
      sme: contact@your.company
    alias: ["CRR", "CRs"]
    indentifier: "crr"

Then could be used referenced in doc macros:

{ % docs mydoc %}
This is a table contains data related to {{ term("crr") }} # would render name and link
{% enddocs %}

Then Ideally in the dbt docs, in the description, it would render a link to the item in the glossary being referenced or render a preview on hover.

Describe alternatives you've considered

Could be achieved via a terms macro or extending the docs macro functionality.

Additional context

This is database agnostic and purely for informational purposes

Who will this benefit?

I think this could benefit all DBT users or consumers of DBT docs. The ability to define terms provides valuable context. Even a well detailed catalog isn't as useful if the descriptions make references to terms that assume user knows what they mean. This would help keep things DRY by allowing dbt users to define terms once and reference elsewhere.

Are you interested in contributing this feature?

I'm definitely interested in contributing to this feature, might need help in the frontend department.

[jtcohen6]

Neat idea, @datGnomeLife.

I definitely recall hearing a desire for docs blocks that can reference other docs blocks, as a way of reducing repeated code. I like how you've framed it here, though: it's not just an add-on to docs, but also a new point of entry for docs viewers. They might start with a compiled glossary, look for terms that interest them, find models with descriptions that reference those terms, and end up at the DAG viz to understand the lineage of those models.

The meta/owner piece is especially interesting, as a way of enabling the cross-application or inheritance of responsibility. Today, I think of teams or individual maintainers owning higher-level assets—models that map to views/tables, or exposures that map to dashboards/apps/UIs—but this implementation of terms would bring us a half-step closer to the business of column-level lineage, a thing which dbt isn't quite able to support today.

I don't foresee taking immediate action here; a significant rework of dbt-docs remains on the longer-term roadmap. In the meantime, I'm interested to see what other folks think.

[dolodort2]

This would be great! We're trying to hack together a "glossary" right now via existing dbt docs functionality. Looking forward to seeing progress here.

[github-actions]

This issue has been marked as Stale because it has been open for 180 days with no activity. If you would like the issue to remain open, please remove the stale label or comment on the issue, or it will be closed in 7 days.