Wie Sie Data-Dokumentation mit Ihrem wachsenden Stack synchron halten

1. Das Dokumentations-Drift-Problem

Jede Data-Organisation kennt das: Neue Kollegin fragt, was diese Tabelle macht. Sie schicken den Wiki-Link. Zehn Minuten später: "Im Doc steht, die Spalte ist required, aber 40% sind null." Die Docs wurden vor acht Monaten zuletzt aktualisiert.

Warum Dokumentation driftet

2. Die Kosten veralteter Dokumentation

Veraltete Docs sind nicht nur nervig – sie sind teuer. Das passiert, wenn Dokumentation nicht mit der Realität übereinstimmt.

3. Automation-First-Ansatz

Der Kern: Dokumentation wird extrahiert, nicht geschrieben. Statt Engineers manuell pflegen zu lassen, ziehen Sie Metadaten automatisch aus Systemen und ergänzen sie um menschlichen Kontext.

So funktioniert Automatisierung in der Praxis

4. Was automatisieren, was manuell dokumentieren

Nicht alles gehört automatisiert. Nicht alles gehört manuell. So entscheiden Sie.

# models/marts/revenue/monthly_revenue.sql
{{
  config(
    materialized='table',
    description='Monthly revenue aggregated from orders. **Caveat**: Excludes refunds processed >30 days after order.'
  )
}}

-- Column-level docs in schema.yml
version: 2
models:
  - name: monthly_revenue
    description: |
      Monthly revenue by product category.
      
      **Calculation**: SUM(order_total) WHERE order_status = 'completed'
      **Owner**: [email protected]
      **SLA**: Updates daily at 6 AM UTC
    columns:
      - name: month
        description: Calendar month (YYYY-MM-01)
      - name: category
        description: Product category from dim_products
      - name: revenue
        description: |
          Total revenue in USD. 
          **Note**: Does not include tax or shipping.

5. Dokumentation in den Workflow integrieren

Docs bleiben aktuell, wenn sie Teil des Entwicklungsprozesses sind – nicht danach. Hier die wichtigsten Integrationspunkte.

## Documentation Checklist
- [ ] dbt model has description
- [ ] New columns have descriptions
- [ ] Calculation logic is documented
- [ ] Owner is specified in schema.yml
- [ ] Known caveats are noted

# Check that all models have descriptions
SELECT 
  model_name
FROM {{ ref('dbt_models') }}
WHERE description IS NULL 
  OR description = ''
  OR description = 'TODO'
-- This test will fail if any models are undocumented

6. Tools für Dokumentationsautomatisierung

Der Modern Data Stack bietet starke Tools, um Docs synchron zu halten. So greifen sie ineinander.

Empfohlener Tool-Stack nach Teamgröße

7. Best Practices, um Docs synchron zu halten

8. Häufige Fragen