Technische Dokumentation & Wissensmanagement -- strukturiert, versioniert, automatisiert

Positionierung

Technische Dokumentation ist in Daten- und DWH-Projekten oft das erste Opfer von Zeitdruck. Abnahmen werden genehmigt, Systeme gehen in Betrieb -- und die Dokumentation bleibt lückenhaft oder veraltet. Das Ergebnis zeigt sich später: bei der Einarbeitung neuer Kollegen, bei der Fehlersuche in schlecht dokumentierten ETL-Strecken, beim Wechsel von Betriebsverantwortlichen. Ich bringe technische Dokumentation als gleichberechtigte Lieferpflicht in jedes Projekt ein -- nicht als Anhang, sondern als integralen Bestandteil.

Mein Hintergrund liegt in der Datenbankentwicklung, im DWH-Aufbau und im Infrastrukturbetrieb. Ich schreibe Dokumentation nicht aus der Perspektive eines reinen Technischen Redakteurs, sondern als jemand, der die zugrunde liegenden Systeme selbst entwickelt und betrieben hat. Diese Verbindung -- technische Tiefe und Dokumentationserfahrung -- erlaubt es mir, Data Dictionaries zu schreiben, die wirklich korrekt sind, Runbooks zu erstellen, die im Einsatz funktionieren, und Architekturkonzepte zu formulieren, die Entscheidungen nachvollziehbar machen.

Konkrete Referenzen: Bei einem Versicherungsunternehmen habe ich an einem webbasierten, XML-gestützten DB-Dokumentationssystem mitgewirkt und weiterentwickelt. Beim Öffentlichen Auftraggeber / Forschungsbereich habe ich Anforderungs- und Testdokumentation in einem regulierten DWH-Umfeld erstellt und gepflegt. Für meinen Eigenbetrieb / Infrastruktur-Bereich habe ich eine zentrale Betriebsdokumentation aufgebaut, die automatisierte Konfigurationssicherung integriert.

Dokumentation ist auch eine Frage des Formats. Nicht jede Doku gehört in eine Word-Datei oder ein Confluence-Wiki. Runbooks profitieren von Versionierung in Git. Data Dictionaries lassen sich aus Datenbankmetadaten automatisch generieren. Architekturkonzepte gewinnen durch Diagramme, die neben dem Text gepflegt werden. Ich wähle Format und Werkzeug nach dem Verwendungszweck -- und setze dabei auf offene, langlebige Standards.

Stellenwert technischer Dokumentation im DWH- und Infrastruktur-Umfeld

In Daten- und DWH-Projekten umfasst Dokumentation weit mehr als eine technische Beschreibung von Tabellen und Feldern. Sie umfasst die fachliche Bedeutung der Daten, die Herkunft (Quellsysteme, Transformationslogik), die Abhängigkeiten zwischen Tabellen und ETL-Strecken, die Betriebsabläufe für Monitoring und Fehlerbehandlung sowie die Testdokumentation für Abnahmen. Ein vollständiges Dokumentationsbild hat mindestens vier Ebenen: die Konzeptebene (Architektur, Entscheidungen), die Betriebsebene (Betrieb, Monitoring, Konfiguration), die Runbook-Ebene (Schritt-für-Schritt für wiederkehrende Aufgaben) und die Datenebene (Data Dictionary, Lineage, Metadaten).

Die vier Ebenen technischer Dokumentation: von Architekturentscheidungen und Betriebsanleitungen über Runbooks bis zum vollständigen Data Dictionary. Alle Ebenen in Git versioniert und im Wiki oder als statisches HTML veroffentlicht.

Wissenssilos und ihre Konsequenzen

Wissenssilos entstehen, wenn Dokumentation im Kopf einzelner Personen verbleibt statt in schriftlicher, auffindbare Form. Im DWH-Umfeld ist das besonders kritisch: Wenn nur eine Person weiss, wie ein bestimmtes ETL-Paket die Quelldaten transformiert oder welche Spalte in einer Faktentabelle welche Geschäftsregel implementiert, hat das Team ein Einzelpunktrisiko. Die Konsequenzen sind Einarbeitungszeiten von Wochen statt Tagen, Fehler bei Erweiterungen wegen mangelnden Kontexts und Betriebsunterbrechungen, die vermeidbar wären.

Dokumentation als messbare Investition

Der Aufwand für Dokumentation zahlt sich schnell aus: Eine vollständige Betriebsdoku reduziert Einarbeitungszeiten neuer Teammitglieder erheblich. Automatisierte Data-Dictionary-Generierung aus Datenbankmetadaten spart Stunden manueller Pflegearbeit pro Woche. Versionierte Runbooks verhindern, dass im Stressfall des Produktionsvorfalls wichtige Schritte vergessen werden. Anforderungsdokumentation schützt beide Seiten -- Auftraggeber und Dienstleister -- bei Streitigkeiten über den vereinbarten Leistungsumfang.

• Konzeptdokumentation: Architekturentscheidungen, Systemgrenzen, Integrationspunkte
• Betriebsdokumentation: Serverübersichten, Konfigurationen, Ansprechpartner, SLAs
• Runbooks: Wiederkehrende Aufgaben, Fehlerbehandlung, Notfallprozesse Schritt für Schritt
• Data Dictionary: Tabellen, Views, Spalten, Datentypen, fachliche Bedeutung, Beziehungen
• Data Lineage: Herkunft und Transformation von Daten durch alle Schichten
• Schnittstellendokumentation: API-Parameter, Datenformate, Schnittstellen zu Fremdsystemen
• Anforderungsdokumentation: fachliche Anforderungen, Akzeptanzkriterien, offene Punkte
• Testdokumentation: Testfälle, Ergebnisse, Abnahmeprotokolle

Ich empfehle, Dokumentation von Beginn an als Teil des Projekts zu planen -- mit definierten Lieferbestandteilen, zugewiesenen Verantwortlichkeiten und einem Review-Prozess, der die Qualität sichert. Eine Dokumentation, die erst am Ende als Nacharbeit entsteht, ist meist lückenhaft und veraltet sie rasch.

Betriebsdokumentation & Runbooks

Betriebsdokumentation ist das Gedächtnis einer IT-Umgebung. Sie beschreibt, was vorhanden ist (Inventar, Konfigurationen, Schnittstellen), wie es betrieben wird (Prozesse, Aufgaben, Zeitpläne) und was im Fehlerfall zu tun ist (Runbooks, Eskalationspfade). Ohne diese Grundlage hängt der Betrieb vom Wissen einzelner Personen ab -- ein Risiko, das sich spätestens dann materialisiert, wenn diese Personen nicht erreichbar sind.

In meinem Eigenbetrieb / Infrastruktur-Bereich, der auf Proxmox VE, Debian, NGINX, WireGuard und verschiedenen Diensten basiert, habe ich eine zentrale Betriebsdokumentation aufgebaut, die automatisierte Konfigurationssicherung integriert. Änderungen an Konfigurationen werden automatisch als Textdateien gesichert und versioniert -- so ist der Ist-Zustand jederzeit nachvollziehbar, ohne manuelle Doku-Pflege.

Struktur einer Betriebsdokumentation

Eine sinnvolle Betriebsdokumentation folgt einer konsistenten Struktur. Auf der obersten Ebene steht das Inventar: Alle Server, Dienste, Schnittstellen, Zugänge und Verantwortlichkeiten. Darunter folgen systemspezifische Abschnitte, die Konfigurationsdetails, Abhängigkeiten und Betriebshinweise enthalten. Die dritte Ebene umfasst Runbooks für wiederkehrende Aufgaben und Notfallprozesse.

Runbooks: handhabbar und getestet

Ein Runbook ist nur dann wertvoll, wenn es im Einsatz funktioniert. Das bedeutet: konkrete Schritt-für-Schritt-Anweisungen, keine Interpretationsspielräume, Angaben zu vorausgesetzten Rechten und Werkzeugen sowie eine Ausführungszeit, die realistisch ist. Runbooks müssen regelmäßig getestet werden -- ein Runbook, das seit zwei Jahren nicht ausgeführt wurde, ist möglicherweise veraltet. Die Versionierung in Git macht Änderungen nachvollziehbar und verhindert, dass verschiedene Teams mit unterschiedlichen Versionen arbeiten.

# Runbook: SQL Server Agent -- Neustart nach geplantem Patching

## Metadaten
- **Version**: 1.3
- **Letzter Test**: 2025-04-15
- **Getestet von**: DBA-Team
- **Gilt fuer**: SQL Server 2019 / 2022 on-premises

## Voraussetzungen
- Windows-Konto mit lokalen Administratorrechten auf dem Zielserver
- PowerShell 5.1+ oder PowerShell 7+
- dbatools-Modul installiert (Import-Module dbatools)

## Ablauf

### Schritt 1: Aktive Jobs pruefen und beenden
```powershell
# Alle aktuell laufenden SQL Agent Jobs anzeigen
Get-DbaAgentJob -SqlInstance 'sql-prod-01' | Where-Object { $_.CurrentRunStatus -eq 'Executing' }
# Jobs stoppen, falls notwendig
Stop-DbaAgentJob -SqlInstance 'sql-prod-01' -Job 'ETL_Nacht_Vollimport'
```

### Schritt 2: Dienst planmaessig beenden
```powershell
Stop-DbaService -SqlInstance 'sql-prod-01' -Type Agent
# Statuscheck nach 30 Sekunden
Start-Sleep 30
Get-DbaService -SqlInstance 'sql-prod-01' | Select-Object ServiceName, State
```

### Schritt 3: Patching abwarten (manuell durch Patch-Team)

### Schritt 4: Dienst neu starten und pruefen
```powershell
Start-DbaService -SqlInstance 'sql-prod-01' -Type Agent
# Alle Jobs im Status 'Idle' = Neustart erfolgreich
Get-DbaAgentJob -SqlInstance 'sql-prod-01' | Select-Object Name, CurrentRunStatus
```

## Fehlerbehandlung
| Symptom                     | Ursache                        | Massnahme                         |
|-----------------------------|--------------------------------|-----------------------------------|
| Dienst startet nicht        | Fehlendes Dienstkonto-Passwort | Passwort in AD pruefen/erneuern   |
| Jobs bleiben im Status Run  | Haengender Job                 | sp_stop_job via T-SQL ausfuehren  |
| Verbindungsfehler nach Start| Netzwerk-Firewall              | Port 1433 im Firewall pruefen     |

## Eskalation
Bei Nichterfolg nach 3 Versuchen: DBA-Rufbereitschaft +49 173 XXXXXXX

Runbooks in Markdown-Format können direkt in Git versioniert und in Confluence oder GitHub Pages veroffentlicht werden. Die Tabelle für Fehlerbehandlung macht das Runbook im Einsatz sofort nutzbar.

Das oben gezeigte Runbook-Template demonstriert den praktischen Nutzen von Markdown für Betriebsdokumentation: klare Struktur, Metadaten-Header für Versionsverfolgung, eingebettete Code-Beispiele die direkt kopiert werden können, und eine Fehlerbehandlungstabelle. Solche Templates lassen sich unternehmensweit standardisieren und als Basis für neue Runbooks verwenden.

Data Dictionary & Datenmodell-Dokumentation

Ein Data Dictionary ist das zentrale Nachschlagewerk für alle Tabellen, Views, Spalten und Beziehungen in einem Datenbankumfeld. Es beantwortet die Fragen, die fachliche Nutzer und Entwickler tagtäglich stellen: Was bedeutet die Spalte 'kunden_status'? Welchen Wertebereich hat sie? Woher kommt sie? Welche Tabellen hängen davon ab? Ohne diese Informationen ist jede Erweiterung oder Fehlersuche mit unnötigem Aufwand verbunden.

In meiner Arbeit bei einer Versicherung habe ich an einem webbasierten, XML-gestützten Datenbankdokumentationssystem mitgewirkt. Dieses System speicherte Metadaten zu Tabellen, Views und Spalten in strukturierter Form und generierte daraus eine HTML-Ansicht, die für Entwickler und fachliche Benutzer zugänglich war. Die Erfahrung aus diesem Projekt hat mein Verständnis dafür geschärft, wie ein Data Dictionary sowohl technisch akkurat als auch fachlich verständlich sein muss.

Struktur eines vollständigen Data Dictionary

Ein vollständiges Data Dictionary enthielt auf Tabellenebene: physischen Namen, logischen Namen, fachliche Beschreibung, Kategorie (Faktentabelle / Dimension / Staging), Quelltabellen und Abhängigkeiten. Auf Spaltenebene: physischen Spaltennamen, logischen Namen, Datentyp, Nullable, Wertebereich, fachliche Bedeutung, Beispielwerte und Transformationsregel (falls abgeleitet). Dazu kommen Beziehungen (Foreign Keys), Partitionierungsinformationen und Versions-/Änderungshistorie.

-- Extrahiert ein vollstaendiges Data Dictionary aus SQL Server Systemsichten.
-- Gibt Tabellen, Spalten, Datentypen, Nullable-Status und erweiterte Properties zurueck.
-- Erweiterte Eigenschaften (MS_Description) koennen ueber SSMS oder sp_addextendedproperty
-- gepflegt und hier direkt ausgelesen werden.

SELECT
    t.TABLE_SCHEMA                          AS schema_name,
    t.TABLE_NAME                            AS table_name,
    t.TABLE_TYPE                            AS object_type,      -- BASE TABLE oder VIEW
    c.COLUMN_NAME                           AS column_name,
    c.ORDINAL_POSITION                      AS col_order,
    c.DATA_TYPE                             AS data_type,
    COALESCE(
        CAST(c.CHARACTER_MAXIMUM_LENGTH AS VARCHAR(10)),
        CAST(c.NUMERIC_PRECISION        AS VARCHAR(10))
    )                                       AS type_detail,
    c.IS_NULLABLE                           AS is_nullable,
    -- Fachliche Beschreibung aus Extended Properties (MS_Description)
    CAST(ep_t.value AS NVARCHAR(500))       AS table_description,
    CAST(ep_c.value AS NVARCHAR(500))       AS column_description
FROM INFORMATION_SCHEMA.TABLES  t
JOIN INFORMATION_SCHEMA.COLUMNS c
    ON  t.TABLE_SCHEMA = c.TABLE_SCHEMA
    AND t.TABLE_NAME   = c.TABLE_NAME
-- Extended Property auf Tabellenebene
LEFT JOIN sys.extended_properties ep_t
    ON  ep_t.major_id    = OBJECT_ID(t.TABLE_SCHEMA + '.' + t.TABLE_NAME)
    AND ep_t.minor_id    = 0
    AND ep_t.name        = 'MS_Description'
-- Extended Property auf Spaltenebene
LEFT JOIN sys.extended_properties ep_c
    ON  ep_c.major_id    = OBJECT_ID(t.TABLE_SCHEMA + '.' + t.TABLE_NAME)
    AND ep_c.minor_id    = c.ORDINAL_POSITION
    AND ep_c.name        = 'MS_Description'
WHERE t.TABLE_SCHEMA NOT IN ('sys','information_schema')
ORDER BY t.TABLE_SCHEMA, t.TABLE_NAME, c.ORDINAL_POSITION;

Diese Abfrage ist der Ausgangspunkt für jede automatisierte Dokumentationsgenerierung. Die MS_Description-Felder können über SSMS, SSDT oder per sp_addextendedproperty gepflegt werden und stehen damit als maschinell lesbare Metadatenquelle bereit.

Foreign Keys und Beziehungsdiagramme

Neben den Tabellen- und Spaltenmetadaten sind die Beziehungen zwischen Tabellen ein wesentlicher Bestandteil des Data Dictionary. Foreign-Key-Beziehungen lassen sich aus sys.foreign_keys und sys.foreign_key_columns extrahieren und in einem Beziehungsdiagramm visualisieren. In grossen Datenmodellen ist ein vollständiges ER-Diagramm oft zu komplex; sinnvoller ist eine thematische Aufgliederung nach Fachbereichen oder Sternschemas.

Docs-as-Code: Markdown, Git und CI/CD

Das Konzept 'Docs-as-Code' behandelt Dokumentation wie Quellcode: Sie wird in Textformaten (Markdown, AsciiDoc, reStructuredText) geschrieben, in Git versioniert, über Pull Requests reviewed und per CI/CD automatisch gebaut und veröffentlicht. Dieses Modell hat gegenüber traditionellen Ansätzen (Word-Dokumente, unversionierte Wikis) klare Vorteile: Jede Änderung ist nachvollziehbar, Reviews können im Code-Review-Prozess integriert werden, und die veroffentlichte Dokumentation ist immer synchron mit dem Stand im Repository.

Der vollständige Docs-as-Code-Workflow: DB-Metadaten und Code-Kommentare werden extrahiert, ein Generator (Sphinx, mkdocs, Python-Skript) baut daraus Markdown oder HTML, die CI/CD-Pipeline führt Review und Tests durch, und das Ergebnis wird in Confluence, GitHub Pages oder als statisches HTML veroffentlicht.

Markdown als universelles Dokumentationsformat

Markdown ist einfach genug, um ohne Werkzeug lesbar zu sein, und mächtig genug, um komplexe Strukturen abzubilden: Tabellen, Code-Blöcke, Bilder, Links und Verschachtelungen. Mit Erweiterungen (Mermaid-Diagramme in GitHub Markdown, Admonitions in mkdocs, Directives in Sphinx) wird Markdown zu einem vollwertigen Dokumentationsformat für technische Inhalte. Der Frontmatter-Header (YAML-Block am Anfang der Datei) erlaubt es, Metadaten wie Autor, Erstellungsdatum, Version und Kategorie strukturiert zu erfassen.

---
# Frontmatter-Struktur fuer technische Dokumentationsartikel
# Wird von mkdocs, Sphinx und vielen anderen Tools ausgewertet.
title:       "Ladeprozess DWH Kundendimension"
slug:        dwh-kundendimension-ladeprozess
category:    ETL-Dokumentation
version:     "2.1"
date:        2025-03-10
last_review: 2025-05-20
reviewed_by: Stefan Corsten
status:      aktiv          # aktiv | veraltet | in-Bearbeitung
tags:
  - DWH
  - ETL
  - Kundendimension
  - SSIS
related:
  - dwh-quellsystem-crm
  - ssis-deployment-prozess
---

# Ladeprozess DWH Kundendimension

## Zweck und Ueberblick
Dieser Artikel beschreibt den SSIS-basierten Ladeprozess fuer die Kundendimension im DWH.
Quellsystem ist das CRM (Tabelle `dbo.customers`), Ziel ist `dim.Kunden` im DWH.

## Geschaeftsregel
- Nur Kunden mit `active_flag = 1` werden geladen.
- Adressaenderungen werden als SCD Typ 2 historisiert.
- Fehlende Postleitzahlen werden mit '00000' substituiert.

## Technische Details
- SSIS-Paket: `Load_DimKunden.dtsx`
- Ausfuehrung: Taeglich 02:30 Uhr, SQL Agent Job `DWH_NightLoad`
- Abhaengigkeit: `Load_Staging_CRM` muss abgeschlossen sein.
- Laufzeit erwartet: 8-12 Minuten

## Fehlerbehandlung
Bei Fehler > 10 abgelehnten Zeilen: Job-Abbruch und Alert an dwh-team@beispiel.de

Der Frontmatter-Header macht Metadaten maschinell auswertbar: mkdocs generiert automatisch Inhaltsverzeichnisse, Suchindizes und Navigationsbäume aus diesen Feldern. Der review-Workflow ist direkt in den Header integriert.

CI/CD für Dokumentation

Eine CI/CD-Pipeline für Dokumentation prüft bei jedem Commit, ob die Dokumentation valide (keine kaputten Links, kein ungültigtes Frontmatter), vollständig (alle Pflichtfelder vorhanden) und konsistent (Verlinkungen zu anderen Artikeln gültig) ist. Nach erfolgreicher Prüfung wird die Dokumentation automatisch in das Zielsystem deployed -- ohne manuelle Freigabeschritte.

# CI-Pipeline fuer Docs-as-Code mit mkdocs
# Wird bei jedem Push auf main oder bei Pull Requests ausgefuehrt.
# Kompatibel mit GitHub Actions (Datei: .github/workflows/docs.yml)

name: Build und Deploy Dokumentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      # Schritt 1: Repository auschecken
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # vollstaendige Git-Historie fuer git-revision-date-Plugin

      # Schritt 2: Python-Umgebung mit mkdocs und Plugins einrichten
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Abhaengigkeiten installieren
        run: |
          pip install mkdocs-material                       mkdocs-git-revision-date-localized-plugin                       mkdocs-minify-plugin                       pymdown-extensions

      # Schritt 3: Doku bauen und auf Links pruefen
      - name: mkdocs build (strikt: Fehler bei kaputten Links)
        run: mkdocs build --strict

      # Schritt 4: Nur auf main deployen (nicht bei Pull Requests)
      - name: Deploy nach GitHub Pages
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: mkdocs gh-deploy --force

  # Optional: Sphinx-basierter Build (fuer Python-Projekte)
  # build-sphinx:
  #   runs-on: ubuntu-latest
  #   steps:
  #     - uses: actions/checkout@v4
  #     - run: pip install sphinx sphinx-rtd-theme
  #     - run: sphinx-build -b html docs/ docs/_build/html -W

Diese Pipeline baut die Dokumentation bei jedem Push, prüft auf kaputte Links im Strict-Modus und deployt auf GitHub Pages. Für GitLab CI ist die Struktur analog mit '.gitlab-ci.yml' und 'pages'-Job-Bezeichnung.

Automatisierte Doku-Generierung aus DB-Metadaten

Die aufwändigste Doku-Aufgabe in Datenbankprojekten ist die Pflege des Data Dictionary. Hunderte von Tabellen und Tausende von Spalten manuell zu dokumentieren ist zeitaufwändig und fehleranfällig -- und veraltete Dokumentation ist schlimmer als keine, weil sie aktiv in die Irre führt. Die Lösung: automatische Generierung der technischen Grundstruktur aus Datenbankmetadaten, kombiniert mit manuell gepflegten fachlichen Beschreibungen.

Der Doku-Generierungsfluss: DB-Metadaten (sys.tables, INFORMATION_SCHEMA, SSIS-Katalog) werden per Python- oder PowerShell-Skript extrahiert, als Markdown-Dateien aufbereitet und per CI/CD in Confluence oder als statisches HTML veroffentlicht.

Python-basierte Markdown-Generierung aus DB-Metadaten

Mit Python lassen sich aus den zuvor beschriebenen SQL-Abfragen vollständige Markdown-Dokumente generieren: Eine Datei pro Tabelle oder Schema-Gruppe, mit Spalten-Tabelle, Metadaten-Header, Beziehungshinweisen und einer Platzhaltersektion für manuell ergänzte fachliche Beschreibungen. Das Skript läuft in der CI-Pipeline oder per SQL Agent Job und aktualisiert die Doku bei jeder Schema-Änderung automatisch.

#!/usr/bin/env python3
# Generiert Markdown-Dateien als Data-Dictionary-Doku aus SQL Server Metadaten.
# Verbindung via pyodbc, Ausgabe als eine Markdown-Datei pro Tabelle.
# Voraussetzung: pip install pyodbc

import pyodbc
import os
import re

# Verbindungsparameter (in Produktion aus KeyVault oder Umgebungsvariable lesen)
CONN_STR = (
    "DRIVER={ODBC Driver 18 for SQL Server};"
    "SERVER=localhost;"
    "DATABASE=DWH_Produktion;"
    "Trusted_Connection=yes;"
)
OUT_DIR = "./docs/data-dictionary"

# SQL: Tabellen und Spalten mit Extended Properties laden
SQL = '''
    SELECT
        t.TABLE_SCHEMA    AS schema_name,
        t.TABLE_NAME      AS table_name,
        c.COLUMN_NAME     AS col_name,
        c.ORDINAL_POSITION AS col_order,
        c.DATA_TYPE       AS data_type,
        COALESCE(
            CAST(c.CHARACTER_MAXIMUM_LENGTH AS NVARCHAR(10)),
            CAST(c.NUMERIC_PRECISION        AS NVARCHAR(10))
        )                 AS type_detail,
        c.IS_NULLABLE     AS nullable,
        CAST(ep_t.value AS NVARCHAR(500)) AS tbl_desc,
        CAST(ep_c.value AS NVARCHAR(500)) AS col_desc
    FROM INFORMATION_SCHEMA.TABLES  t
    JOIN INFORMATION_SCHEMA.COLUMNS c
        ON  t.TABLE_SCHEMA = c.TABLE_SCHEMA
        AND t.TABLE_NAME   = c.TABLE_NAME
    LEFT JOIN sys.extended_properties ep_t
        ON  ep_t.major_id = OBJECT_ID(t.TABLE_SCHEMA+'.'+t.TABLE_NAME)
        AND ep_t.minor_id = 0 AND ep_t.name = 'MS_Description'
    LEFT JOIN sys.extended_properties ep_c
        ON  ep_c.major_id = OBJECT_ID(t.TABLE_SCHEMA+'.'+t.TABLE_NAME)
        AND ep_c.minor_id = c.ORDINAL_POSITION AND ep_c.name = 'MS_Description'
    WHERE t.TABLE_SCHEMA NOT IN ('sys','information_schema')
    ORDER BY t.TABLE_SCHEMA, t.TABLE_NAME, c.ORDINAL_POSITION
'''

def sanitize(name):
    # Dateinamen aus Tabellennamen ableiten (nur alphanumerisch + Bindestrich)
    return re.sub(r'[^a-zA-Z0-9_-]', '_', name).lower()

def gen_markdown(schema, table, tbl_desc, columns):
    # Markdown-Datei fuer eine einzelne Tabelle generieren
    lines = [
        f"---",
        f"title: "{schema}.{table}"",
        f"category: Data Dictionary",
        f"generated: auto",
        f"---",
        f"",
        f"# {schema}.{table}",
        f"",
        f"{tbl_desc or '_Keine fachliche Beschreibung vorhanden -- bitte erganzen._'}",
        f"",
        f"## Spalten",
        f"",
        f"| # | Spaltenname | Datentyp | Nullable | Beschreibung |",
        f"|---|-------------|----------|----------|--------------|",
    ]
    for col in columns:
        dtype = col['data_type']
        if col['type_detail']:
            dtype += f"({col['type_detail']})"
        desc = col['col_desc'] or ''
        lines.append(
            f"| {col['col_order']} | `{col['col_name']}` | {dtype} "
            f"| {col['nullable']} | {desc} |"
        )
    lines += ["", "## Beziehungen", "", "_Bitte manuell erganzen._", ""]
    return "\n".join(lines)

def main():
    os.makedirs(OUT_DIR, exist_ok=True)
    conn = pyodbc.connect(CONN_STR)
    cursor = conn.cursor()
    cursor.execute(SQL)
    rows = cursor.fetchall()
    cols = [d[0] for d in cursor.description]

    # Zeilen nach Tabelle gruppieren
    tables = {}
    for row in rows:
        rec = dict(zip(cols, row))
        key = (rec['schema_name'], rec['table_name'])
        if key not in tables:
            tables[key] = {'desc': rec['tbl_desc'], 'cols': []}
        tables[key]['cols'].append(rec)

    # Pro Tabelle eine Markdown-Datei schreiben
    for (schema, table), data in tables.items():
        md = gen_markdown(schema, table, data['desc'], data['cols'])
        fname = os.path.join(OUT_DIR, f"{sanitize(schema)}__{sanitize(table)}.md")
        with open(fname, 'w', encoding='utf-8') as f:
            f.write(md)
        print(f"Generiert: {fname}")

    print(f"Fertig: {len(tables)} Tabellen dokumentiert.")
    conn.close()

if __name__ == "__main__":
    main()

Dieses Skript generiert pro Tabelle eine vollständige Markdown-Datei mit Header, Spalten-Tabelle und Platzhalter für manuelle Ergänzungen. Es kann täglich per SQL Agent oder CI-Pipeline ausgeführt werden und hält die Doku automatisch aktuell.

PowerShell-Alternative für Windows-Umgebungen

In Windows-dominierten Umgebungen kann der gleiche Ansatz mit PowerShell realisiert werden. Das dbatools-Modul bietet Get-DbaDbTable und Get-DbaDbColumn, die ohne SQL-Abfragen direkt die Metadaten liefern. Kombiniert mit Out-File oder Set-Content lassen sich Markdown-Dateien direkt aus PowerShell generieren.

Confluence & Wiki-Strukturierung

Confluence ist in vielen Organisationen das zentrale Wissensmanagementsystem für technische und fachliche Dokumentation. Wie jedes Wiki kann es jedoch schnell zur unstrukturierten Ablage werden: veraltete Seiten, inkonsistente Benennung, fehlende Verlinkungen, unklare Verantwortlichkeiten. Eine sinnvolle Confluence-Struktur erfordert von Beginn an ein durchdachtes Konzept für Spaces, Seitentypen, Namenskonventionen und Review-Prozesse.

Space-Konzept und Seiten-Hierarchie

Ich strukturiere Confluence-Spaces nach dem Nutzungszweck: ein technischer Space für Betriebsdokumentation und Runbooks, ein Projekt-Space für Anforderungen und Testdokumentation, ein Data-Space für Data Dictionary und Lineage-Informationen. Innerhalb jedes Space folgt die Seitenhierarchie einer konsistenten Vorlage: Übersichtsseite (Scope, Links zu Unterabschnitten), Systemspezifische Seiten, Einzelne Runbooks oder Dictionary-Einträge.

Namenskonventionen und Metadaten-Labels

Einheitliche Seitentitel und Labels sind der Schlüssel zu einer durchsuchbaren Confluence-Struktur. Seitentitel folgen einem Schema: '[System] -- [Thema] -- [Typ]', z. B. 'DWH-Prod -- Kundendimension -- Ladeprozess'. Labels erlauben Cross-Space-Suche: 'runbook', 'data-dictionary', 'incident-response', 'sla-relevant'. Confluence-Makros wie 'Seitenbaum' und 'Inhalt nach Label' generieren automatisch Übersichtsseiten ohne manuelle Pflege.

Migration von Word-Dokumenten und SharePoint nach Confluence

Die Migration von bestehender Dokumentation aus Word-Dateien oder SharePoint nach Confluence ist ein häufiges Szenario. Die technische Migration (Import per API oder Confluence-Import-Tool) ist dabei oft einfacher als die inhaltliche Bereinigung: Veraltete Inhalte aussortieren, fehlende Informationen erkennen, Verlinkungen herstellen. Ich begleite solche Migrationen sowohl technisch als auch inhaltlich und sorge dafür, dass das Ergebnis eine navigierbare, aktuelle Wissensbasis ist -- keine digitale Ablage alter Dokumente.

• Confluence Space-Konzept: technische Doku, Projekt-Doku, Data Dictionary als getrennte Spaces
• Seiten-Templates: einheitliche Frontmatter-Struktur, Review-Datum, Verantwortlichkeit
• Namenskonventionen: [System] -- [Thema] -- [Typ] als konsistentes Benennungsschema
• Labels und Makros: Cross-Space-Suche, automatische Übersichtsseiten
• Migration: Word/SharePoint nach Confluence mit inhaltlicher Bereinigung
• Archivierungsprozess: veraltete Seiten kennzeichnen statt löschen

Data Lineage & Metadaten-Dokumentation

Data Lineage beschreibt den Weg von Daten durch alle Transformationsschritte: vom Quellsystem über Staging und DWH bis zum BI-Frontend. Diese Information ist für Audits, Fehlersuche und Compliance gleichermassen unverzichtbar. Wenn ein Kennwert in einem Report falsch ist, muss nachvollziehbar sein, aus welcher Quelle er stammt, welche Transformationsregeln angewendet wurden und wo in der Kette ein Fehler eingetreten sein könnte.

Vollständige Data Lineage ist selten in einem einzelnen Werkzeug abbildbar. In SSIS-basierten Umgebungen liefert der SSIS-Katalog (SSISDB) Informationen über Paket-Ausführungen und Datenflüsse. In Azure Data Factory stehen Activity Logs und Monitoring zur Verfügung. Ich kombiniere diese Quellen mit einer Markdown-basierten Lineage-Dokumentation, die für Menschen verständlich und in Git versioniert ist.

SSIS-Katalog als Metadatenquelle

Der SSIS-Katalog (SSISDB) ist eine unterschätzte Metadatenquelle. Er enthält nicht nur Ausführungs-Logs, sondern auch strukturierte Informationen über Paketparameter, Verbindungen und die Paketkonfiguration. Mit T-SQL-Abfragen auf SSISDB.catalog lässt sich ein vollständiges Inventar aller SSIS-Pakete, ihrer Verbindungen und Parameter erstellen -- die Grundlage für eine automatisierte Lineage-Dokumentation.

Metadaten aus ADF und Azure Synapse

In Azure-Umgebungen liefern Azure Data Factory und Synapse Analytics ähnliche Metadaten über ihre REST-APIs. Pipelines, Datasets und Linked Services lassen sich per Azure PowerShell oder Python (azure-mgmt-datafactory) abfragen und in eine Lineage-Dokumentation überführen. Diese automatisch generierte Basis wird mit manuell erstellten Flussdiagrammen ergänzt, die fachliche Zusammenhänge darstellen, die aus Metadaten allein nicht ablesbar sind.

• SSIS-Katalog: Pakete, Verbindungen, Parameter, Ausführungs-Logs als Metadatenquelle
• ADF / Synapse: Pipeline-Metadaten via REST API oder azure-mgmt-datafactory
• Markdown-Lineage: tabellarische Darstellung von Quell-Ziel-Beziehungen
• Mermaid-Diagramme: automatisch generierte Flussdiagramme aus Metadaten
• Versionshistorie: Schema-Änderungen und Transformationsregeln rückverfolgbar
• Audit-Unterstützung: Lineage-Doku als Nachweisdokument für Compliance-Anforderungen

Ein zentrales Lineage-Dokument, das tabellarisch für jede Kennzahl / jedes Datenfeld die Quelle, die Transformationsregel und das Ziel beschreibt, ist oft ausreichend für Audit-Zwecke. Es muss nicht vollautomatisiert sein -- wichtiger ist, dass es vollständig und aktuell ist. Ein hybrider Ansatz (automatische Basis + manuelle Ergänzungen) ist in der Praxis oft der beste Kompromiss.

Anforderungs- & Testdokumentation

Anforderungsdokumentation ist in DWH- und Datenprojekten besonders wichtig, weil fachliche und technische Anforderungen eng miteinander verwoben sind. Eine schlecht dokumentierte fachliche Anforderung führt zu technischen Implementierungen, die beim Abnahmetest überraschungen produzieren. Ich erstelle Anforderungsdokumentation, die sowohl für Auftraggeber als auch für Entwickler verständlich ist -- mit klaren Akzeptanzkriterien, die eindeutig testen lassen, ob eine Anforderung erfuellt ist.

Beim Öffentlichen Auftraggeber / Forschungsbereich habe ich in einem streng regulierten DWH-Umfeld Anforderungs- und Testdokumentation erstellt und gepflegt. Die besonderen Anforderungen des öffentlichen Sektors an Nachvollziehbarkeit, Versionierung und formale Abnahme haben mein Verständnis für die Qualitätsanforderungen an Dokumentation in regulierten Umgebungen geschärft.

Anforderungsstruktur für DWH-Projekte

Eine Anforderung im DWH-Umfeld sollte folgende Elemente enthalten: eindeutige ID, fachlicher Kontext (Quelle, Ziel, Zweck), technische Beschreibung (Transformationsregel, Datentypen, Ausnahmen), Akzeptanzkriterien (prüfbar, messbar), Abhängigkeiten (andere Anforderungen, Quellsysteme), Priorität und Status. Diese Struktur erlaubt es, Anforderungen mit Testfällen zu verknüpfen und beim Abnahmetest systematisch abzuarbeiten.

Testdokumentation und Abnahmeprotokolle

Testdokumentation umfasst mehr als die blossen Testergebnisse. Sie dokumentiert den Testrahmen (welche Umgebung, welche Daten, wer hat getestet), die Testfälle (was wird geprüft, welches Ergebnis wird erwartet), die tatsächlichen Ergebnisse und offene Punkte. Abnahmeprotokolle formalisieren den Entscheid des Auftraggebers und schaffen eine verlassliche Grundlage für Folgearbeiten.

• Anforderungs-ID und Versionierung: jede Änderung nachvollziehbar
• Akzeptanzkriterien: messbar, prüfbar, eindeutig formuliert
• Testfälle: positive Tests, negative Tests, Grenzwert-Tests
• Traceability-Matrix: Anforderung zu Testfall zu Abnahmeergebnis
• Abnahmeprotokoll: Datum, Tester, Ergebnis, Vorbehalt, Unterschrift
• Offene-Punkte-Liste: verbleibende Mängel mit Fälligkeit und Verantwortlichkeit

Wissenstransfer & Schulungsmaterial

Am Ende eines Projekts sollte das interne Team eigenständig weitermachen können. Das ist mein Grundsatz, und er gilt nicht nur für Betriebsdokumentation, sondern auch für den aktiven Wissenstransfer: Schulungen, Pair-Programming-Sessions, annotierte Code-Reviews und schriftliche Tutorials, die erklären, warum etwas so implementiert wurde -- nicht nur wie.

Dokumentation als Schulungsmaterial

Gut strukturierte Betriebsdokumentation und Runbooks sind gleichzeitig Schulungsmaterial. Ein neuer Kollege, der ein vollständiges Runbook für den monatlichen DWH-Ladeprozess vorfindet, kann diesen Prozess nach einer begleiteten Durchführung selbst ausführen. Das ist effizienter als jede formale Schulung. Ich schreibe Dokumentation mit dieser Zweckbestimmung explizit im Blick: verständlich für jemanden, der das System noch nicht kennt.

Glossar und Namenskonventionen

Ein Glossar, das fachliche Begriffe, technische Abkürzungen und organisationsspezifische Termini definiert, ist oft die unterschätzte Grundlage aller anderen Dokumentation. Wenn 'Kunde' im Quellsystem etwas anderes bedeutet als im DWH, und niemand das explizit dokumentiert hat, entstehen Missverständnisse auf allen Ebenen. Namenskonventionen für Tabellen, Spalten, SSIS-Pakete und Variablen -- schriftlich festgehalten und durchgängig eingehalten -- reduzieren die kognitive Last bei der Arbeit mit einem fremden System erheblich.

Mehrsprachige Dokumentation

In internationalen Projekten ist mehrsprachige Dokumentation manchmal erforderlich: eine deutsche Betriebsdoku für das lokale IT-Team, eine englische API-Dokumentation für externe Partner, eine portugiesischsprachige Benutzerdoku für brasilianische Standorte. Ich erstelle Dokumentation auf Deutsch, Englisch und Portugiesisch und kenne die inhaltlichen Herausforderungen mehrsprachiger Doku: Konsistenz der Terminologie, Synchronhaltung nach Änderungen, und die Unterschiede im Sprachstil zwischen technischen Texten in verschiedenen Sprachen.

• Pair-Programming und Code-Reviews als informeller Wissenstransfer
• Annotierte Tutorials: erklären Warum, nicht nur Wie
• Glossar: fachliche und technische Begriffe, Abkürzungen, organisationsspezifische Termini
• Namenskonventionen: schriftlich, verbindlich, mit Beispielen
• Mehrsprachige Doku: DE / EN / PT, terminologisch konsistent
• Onboarding-Pakete: Dokumentationsbaum + Runbooks + Glossar für neue Teammitglieder

Vorgehen in der Zusammenarbeit

Der Start eines Dokumentationsprojekts beginnt mit einer Bestandsaufnahme: Was ist bereits dokumentiert? Was fehlt? In welchem Format liegt vorhandene Dokumentation vor? Wer sind die Nutzer der Dokumentation, und welche Fragen müssen sie damit beantworten können? Diese Analyse dauert typischerweise ein bis zwei Tage und ist die Grundlage für einen realistischen Umsetzungsplan.

• Bestandsaufnahme: vorhandene Doku, Lücken, Formate, Nutzergruppen
• Konzept: Dokumentationsstruktur, Werkzeuge, Versionierungsstrategie
• Automatisierung: Metadaten-Extraktion, CI/CD-Pipeline für Doku-Build
• Erstellung: Betriebsdoku, Runbooks, Data Dictionary, Anforderungsdoku
• Review: Inhaltliche Prüfung durch Fachexperten und technische Prüfung
• Publikation: Deployment in Confluence, GitHub Pages oder internes Portal
• Übergabe: Pflegeprozesse, Verantwortlichkeiten, Review-Zyklen definieren

Ich arbeite remote, hybrid oder vor Ort. Für die Erstellung von Betriebsdoku und Data Dictionary ist Remote-Arbeit gut geeignet; für Workshops zur Anforderungsaufnahme und für den Wissenstransfer an interne Teams ist persönliche Anwesenheit oft effektiver. Die Arbeitsweise passe ich dem Projekt an.

Ein wichtiger Aspekt meines Vorgehens ist die Einbeziehung des internen Teams von Beginn an. Dokumentation, die von aussen kommt und vom internen Team nicht mitgetragen wird, wird nicht gepflegt. Ich binde Fachexperten und Entwickler aktiv ein -- durch Reviews, durch gemeinsame Erarbeitung von Glossar und Namenskonventionen und durch die Übergabe von Doku-Werkzeugen und -prozessen, die das Team nach dem Engagement selbst weiterführen kann.

Typische Leistungen im Bereich Technische Dokumentation

Das Leistungsspektrum im Bereich Technische Dokumentation und Wissensmanagement reicht von der einmaligen Doku-Erstellung bis zum Aufbau dauerhafter Strukturen und Prozesse. Je nach Projektphase und Bedarf übernehme ich einzelne Bereiche oder das vollständige Spektrum.

• Betriebsdokumentation: Serverinventare, Konfigurationshandbücher, Ansprechpartner-Verzeichnisse
• Runbooks: Schritt-für-Schritt für Ladeprozesse, Monats-Jobs, Fehlerbehandlung, Notfallprozesse
• Data Dictionary: Extraktion aus DB-Metadaten, fachliche Anreicherung, HTML/Markdown/Confluence
• Data Lineage: Quell-Ziel-Dokumentation, Transformationsregeln, Lineage-Diagramme
• Docs-as-Code: Markdown/AsciiDoc-Strukturen, mkdocs/Sphinx-Setup, CI/CD-Pipeline für Doku
• Automatisierung: Python/PowerShell-Skripte zur Doku-Generierung aus Metadaten
• Confluence-Strukturierung: Space-Konzept, Templates, Namenskonventionen, Migration
• Anforderungsdokumentation: Anforderungs-IDs, Akzeptanzkriterien, Traceability
• Testdokumentation: Testfälle, Abnahmeprotokolle, Offene-Punkte-Listen
• Schnittstellendokumentation: API-Beschreibungen, Datenformat-Spezifikationen
• Glossar und Namenskonventionen: unternehmensweite Terminologie-Standards
• Wissenstransfer: Schulungen, annotierte Code-Reviews, Onboarding-Pakete
• Mehrsprachige Dokumentation: DE / EN / PT für internationale Projekte

Ich arbeite bevorzugt in Projekten, in denen Dokumentation als Qualitätsmerkmal verstanden wird -- nicht als lästige Pflicht. Das sind typischerweise Projekte in regulierten Umgebungen, größere DWH-Neuprojekte, Migrationsprojekte, in denen Wissen übertragen werden muss, und Infrastrukturprojekte, die dauerhaft betrieben werden sollen. Die Kombination aus technischer Tiefe und Dokumentationserfahrung erlaubt es mir, Doku zu liefern, die wirklich korrekt und nutzbar ist.

Ob als dedizierter Dokumentations-Freelancer, als technischer Autor neben der Entwicklungsarbeit oder als Berater für den Aufbau von Dokumentationsprozessen: Ich passe die Zusammenarbeit dem Bedarf des Projekts an. Remote-Arbeit ist für den größten Teil der Arbeit gut geeignet; Workshops und Reviews profitieren gelegentlich von persönlicher Anwesenheit.

Ausgewählte anonymisierte Referenzprojekte

Häufige Fragen zur Technischen Dokumentation