Het gebruik van dbt doc blocks maakt DRY (Don’t Repeat Yourself) documentatie mogelijk door veldbeschrijvingen centraal in Markdown-bestanden te definiëren. Dit verbetert de consistentie en het onderhoud naarmate projecten groeien. Deze aanpak voorkomt dat je velden in meerdere YAML-bestanden opnieuw moet definiëren en maakt dat aanpassingen direct worden doorgevoerd in alle onderliggende modellen.
Documentatie is vaak één van de meest over het hoofd geziene aspecten van datawerk. We bouwen pipelines, structureren onze modellen en maken dashboards. De mensen die er bij betrokken zijn, begrijpen wat er gebeurt, maar wat als er iemand nieuw bij komt?
Zonder duidelijke documentatie wordt het voor hen moeilijk om er wijs uit te worden.
Met de opkomst van AI wordt dit probleem alleen maar groter. We verwachten dat we met onze data kunnen "praten", maar als die data geen duidelijke definities heeft, hoe kunnen we dan juiste antwoorden verwachten?
Dus hoe maken we datasystemen dan echt meer gestructureerd en bruikbaar? In dbt is er een praktische manier om dit aan te pakken: het gebruik van doc blocks.
In dbt gebruiken we YAML-bestanden om de velden van een tabel te definiëren. Meestal ziet dat er ongeveer zo uit:
models
- name: stg_supabase__location
descrption: Staging model for the locations with source supabase
columns:
- name: location_id
description: Unique identifier for each location
Dit werkt goed voor een enkel model. In de praktijk bouwen modellen meestal op elkaar voort. Het resultaat is dat je dezelfde velden, zoals ID's, altijd opnieuw moet definiëren in elk model.
Wanneer we doc blocks gebruiken, definiëren we onze velden in plaats daarvan in een Markdown-bestand. Hierdoor moeten we elk veld maar één keer definiëren en vult de Jinja templating engine de documentatie in overal waar dat nodig is.
Een voorbeeld van een markdown file
{% docs location_id %}
Unique identifier for each location
{% enddocs %}
Een voorbeeld van een YAML file
models
- name: stg_supabase__location
descrption: Staging model for the locations with source supabase
columns:
- name: location_id
description: {{doc('some_id')}}
Het belangrijkste voordeel van deze aanpak is consistentie. We behouden één enkele, duidelijke definitie voor elk veld. Als er iets verandert, passen we dat op één plaats aan en die wijziging wordt overal direct doorgevoerd.
Naast consistentie verbetert dit ook de onderhoudbaarheid. Naarmate projecten groeien, worden gedupliceerde definities snel moeilijk te beheren en beginnen er meer en meer kleine verschillen te ontstaan.
Het houdt je modellen ook overzichtelijker door de structuur te scheiden van de documentatie.
Het belangrijkste is dat het je data bruikbaarder maakt voor AI. Deze systemen vertrouwen op metadata om data te begrijpen. Dit betekent dat je duidelijke en consistente definities nodig hebt om nauwkeurige antwoorden te genereren. Als je documentatie gefragmenteerd of inconsistent is, zal de output dat ook zijn. Het centraliseren van definities helpt ervoor te zorgen dat zowel mensen als AI vanuit hetzelfde vertrekpunt werken.
Wil je meer weten over AI-ready documentatie of data governance in het algemeen? Contacteer ons nu.
Zet uw data-ambities om in een duidelijke, uitvoerbare strategie. Onze experts werken met u samen om te bepalen waar u nu staat, waar u naartoe wilt en hoe u dat gaat bereiken.