In vielen Data-Projekten wird Dokumentation wie ein lästiges Anhängsel behandelt. Man macht „später mal was dazu“ – oder ein Confluence-Artikel verlinkt auf ein veraltetes Diagramm. Das Problem:

Wenn niemand versteht, was eine Tabelle bedeutet oder woher ein KPI kommt, ist der teuerste Data Stack wertlos.

Moderne Datenplattformen – und insbesondere der Data Lake mit dbt, Unity Catalog & Bundles – bieten heute alle Möglichkeiten, Dokumentation automatisiert, versioniert und direkt im Code zu führen.
Ganz ohne Copy-Paste, und ganz ohne dass jemand händisch PDFs schreibt.

In diesem Artikel zeige ich dir:

• was in eine gute Data-Dokumentation gehört,

• wie du sie mit Tools wie dbt Docs, Unity Catalog Comments oder Markdown aus Code heraus automatisch erzeugst,

• und wie du dafür sorgst, dass sie nicht veraltet – sondern mit deinem Projekt mitwächst.

  
  

Was gehört in eine gute Data-Dokumentation – und für wen?

Dokumentation ist kein Selbstzweck. Sie soll helfen – und zwar verschiedenen Zielgruppen. Deshalb lohnt es sich, vorab zu klären:

🎯 Wer nutzt eigentlich deine Dokumentation?

🧱 Was sollte dokumentiert sein?

Einige Beispiele, die du möglichst automatisiert dokumentieren solltest:

🧾 Auf Tabellenebene:

• Zweck der Tabelle (Was stellt sie dar?)

• Granularität (z. B. "1 Zeile pro Kunde pro Tag")

• Aktualisierungsfrequenz (z. B. täglich, stündlich)

🧩 Auf Spaltenebene:

• Bedeutung (z. B. customer_status = 'active', wenn…)

• Datentyp + mögliche Werte

• Herkunft (falls berechnet oder abgeleitet)

🔄 Auf Modell-/Projektebene:

• Abhängigkeiten zwischen Modellen

• Verantwortlichkeiten (Wer betreut die Tabelle?)

• KPIs und ihre Definitionen

✅ Ziel: Kontext statt nur Struktur

Gute Dokumentation erklärt nicht nur was es gibt, sondern auch warum es existiert – und wie es verwendet werden darf.
Deshalb ist der Anspruch: kontextreiche, strukturierte Dokumentation – möglichst nah am Code, möglichst automatisch gepflegt.

Automatisierte Doku mit dbt Docs: Models, Sources, Tests, Lineage

Wer mit dbt arbeitet, hat bereits ein starkes Tool zur Dokumentation direkt im Code – man muss es nur aktiv nutzen.
dbt Docs ist nicht nur eine visuelle Oberfläche, sondern der Einstieg in eine strukturierte, versionierte Dokumentation, die mit deinem Projekt wächst.

🧱 Dokumentation direkt im Model

Jedes dbt Model (.sql-File) kann über die schema.yml beschrieben werden:

models:
  - name: customer_activity
    description: >
      Enthält Kundeninteraktionen auf täglicher Basis.
      1 Zeile pro Kunde pro Tag.
    columns:
      - name: customer_id
        description: Eindeutige ID des Kunden.
      - name: is_active
        description: Kennzeichnet aktive Kunden basierend auf definierter Business-Logik

✅ Diese Infos werden automatisch in dbt Docs dargestellt.

🔍 Lineage: Abhängigkeiten nachvollziehbar machen

dbt erzeugt automatisch eine visuelle Abhängigkeitsstruktur deiner Modelle:

• Welche Tabelle nutzt welche Quelle?

• Was passiert, wenn ich hier etwas ändere?

• Wie hängen Silver- und Gold-Modelle logisch zusammen?

Gerade in wachsenden Projekten ist diese Impact-Analyse Gold wert – und wird vollständig aus deinen ref()-Verweisen abgeleitet.

🔬 Tests als Teil der Dokumentation

dbt Tests (z. B. not_null, unique, accepted_values) helfen nicht nur bei der Datenqualität –
sie zeigen auch, was fachlich erwartet wird. Auch sie werden in dbt Docs angezeigt.

columns:
  - name: status
    tests:
      - accepted_values:
          values: ['active', 'inactive']

→ Das ist nicht nur ein Test – das ist auch eine klare Business-Regel.

🌐 Deployment & Zugriff

Die generierte Dokumentation kannst du:

• lokal als HTML starten (dbt docs generate && dbt docs serve)

• automatisch deployen z. B. per CI/CD (GitHub Pages, S3, Azure Static Web Apps etc.)

• im Team teilen – versioniert pro Branch oder pro Umgebung

Mit dbt Docs dokumentierst du deine Datenmodelle am selben Ort, an dem du sie entwickelst – und das ist der Schlüssel zu langlebiger, verlässlicher Doku.

Unity Catalog Comments & Tags: Dokumentation direkt an der Quelle

Nicht alle Datenmodelle entstehen in dbt – und nicht jeder im Unternehmen liest YAML-Files.
Deshalb ist es sinnvoll, auch direkt in Databricks selbst zu dokumentieren.
Der Unity Catalog bietet dafür zwei zentrale Mechanismen:

🗒️ COMMENTS: Beschreibungen direkt an Tabellen und Spalten

Mit SQL kannst du Tabellen und Spalten direkt beschreiben:

COMMENT ON TABLE gold.customer_activity IS 'Kundenaktivität auf Tagesebene, 1 Zeile pro Kunde pro Tag';
COMMENT ON COLUMN gold.customer_activity.customer_id IS 'Eindeutige Kunden-ID aus dem CRM-System';

Diese Kommentare sind:

• sichtbar im Databricks UI (Table Explorer)

• abrufbar via DESCRIBE TABLE EXTENDED

• Teil der Metadaten im Unity Catalog – also auch API-zugänglich

Das heißt: Du dokumentierst dort, wo Analyst:innen und BI-Tools lesen.

🏷️ TAGS: Metadaten kategorisieren

Unity Catalog erlaubt das Hinzufügen von Tags – zum Beispiel:

ALTER TABLE gold.customer_activity SET TAGS (
  'sensitivity' = 'confidential',
  'owner' = 'data.team@firma.com',
  'refresh' = 'daily'
);

Damit kannst du systematisch Informationen wie:

• Vertraulichkeit

• Verantwortlichkeit

• Aktualisierungsrhythmus

• Datenprodukt-Zugehörigkeit

an Tabellen und Views anhängen – maschinell auswertbar für Audits, Monitoring oder Kataloge.

🤖 Tags & Comments automatisieren

Wenn du Metadaten bereits in Code oder Config-Dateien hast (z. B. YAML, JSON), kannst du:

• Kommentare & Tags automatisch setzen – z. B. per CI/CD oder Notebook

• Doku synchronisieren, z. B. aus dbt schema.yml → Unity Catalog Tags

• Kontext übergreifend nutzbar machen (Docs, Lineage, Data Catalogs)

💡 Pro-Tipp:
Kombiniere COMMENT, TAGS und Catalog Ownership – so entsteht ein vollständig dokumentierter, gut verwalteter Datenraum.

Eigene Dokumentation via Markdown oder Notebooks: dynamisch, versioniert, integriert

Nicht alle Doku passt in YAML oder SQL-Kommentare – manchmal brauchst du mehr Kontext, Screenshots, Tabellen oder sogar interaktive Beispiele.
Hier kommen Markdown und Notebooks ins Spiel – besonders nützlich in Projekten mit gemischtem Tech-Stack oder vielen Stakeholdern.

📝 Markdown als leichtgewichtiger Standard

Markdown bietet sich an für:

• Projektübersichten (README.md)

• Pipeline-Dokumentationen

• Release Notes & KPI-Beschreibungen

• Beispiel-Queries & Use Cases

Der Vorteil:
Du kannst Markdown-Dateien direkt im Git-Repo versionieren – mit Pull Requests, Reviews und klarer Historie.

# sales_by_region (Gold Layer)

**Zweck:**  
Aggregierter Umsatz pro Region, Monat und Vertriebskanal.

**KPI-Definitionen:**  
- `total_sales`: SUM(order_amount)
- `yoy_growth`: Vergleich zum Vorjahresmonat

👉 Das ist einfach, teamfreundlich und CI/CD-kompatibel.

📒 Notebooks als ausführbare Dokumentation

Wenn du Beispiele mit Live-Code zeigen willst (SQL, PySpark, Pandas), kannst du Dokumentation auch direkt in Notebooks schreiben:

• Markdown-Zellen zur Erklärung

• Code-Zellen mit Beispielabfragen

• Screenshots von BI-Dashboards (z. B. als Kontext)

• Exporte als HTML oder PDF – z. B. für Fachbereiche

💡 Besonders hilfreich für Workshops, Onboarding oder komplexere KPIs.

🔄 Automatisierung & CI/CD

Du kannst z. B.:

• Markdown-Dateien automatisch generieren (aus dbt oder YAML)

• Notebooks validieren oder per CLI exportieren (z. B. databricks workspace export_dir)

• Docs als Teil eines Data Products deployen (z. B. im Repo oder per Static Site Generator)

💡 Use Case: Kombiniert & versioniert

In vielen Projekten hat sich dieses Setup bewährt:

So entsteht eine verteilte, aber strukturierte Doku, die nicht veraltet – weil sie mit dem Code lebt.

Best Practices & wie du Doku im Workflow verankerst

Automatisierte Dokumentation klingt gut – aber funktioniert nur, wenn sie integriert, gepflegt und genutzt wird.
Hier sind die wichtigsten Best Practices, die sich in der Praxis bewährt haben:

✅ 1. Doku ist Teil des Codes – nicht des Nachgangs

• Dokumentiere Modelle, Tabellen und Spalten gleich beim Erstellen

• Nutze Pull Requests, um Doku zu reviewen wie jede andere Änderung

• Automatisiere Validierung z. B. mit dbt build + Checks für fehlende Descriptions

🧩 2. Verschiedene Tools kombinieren – nicht gegeneinander ausspielen

• dbt Docs für Modelltransparenz

• Unity Catalog für zentrale Sichtbarkeit & API-Zugriff

• Markdown oder Notebooks für Kontext, Beispiele & Fachbereichs-Kommunikation

→ So erreichst du sowohl Engineers als auch Analyst:innen & Fachbereiche.

🔁 3. Doku regelmäßig refreshen

• Doku-Builds automatisieren (z. B. bei jedem Merge auf main)

• Tags/Comments synchron halten (ggf. über Jobs oder Skripte)

• Veraltete Felder kennzeichnen oder deprecaten – nie einfach löschen

🧠 4. Doku hilft dir selbst

Gute Dokumentation ist kein Geschenk an andere – sie ist dein Gedächtnis in 6 Monaten.
Und sie macht dich unabhängig von Slack-Nachrichten, alten Tickets oder dem einen Kollegen, der „es noch weiß“.

📌 Fazit

Dokumentation im Data Lake muss nicht manuell, aufwändig oder lästig sein.
Mit den richtigen Tools – dbt, Unity Catalog, Markdown, Notebooks – und etwas Struktur kannst du:

• automatisiert dokumentieren,

• versioniert ausliefern und

• kontextreich kommunizieren, was deine Daten tun.

Das Beste:
Du musst es nicht „irgendwann“ machen – du kannst es direkt in deinen Workflow integrieren.