Confluence-Dokumentation automatisieren: Von manuellen Updates zu CI/CD

Das Problem der Dokumentationsschulden

Dokumentationsschulden sammeln sich leise an. Eine Funktion wird ausgeliefert, die Confluence-Seite kurz aktualisiert und alle machen weiter. Einen Monat später ist die Seite leicht falsch. Sechs Monate später beschreibt sie ein System, das nicht mehr existiert. Ein Jahr später führt sie neue Entwickler bei der Einarbeitung aktiv in die Irre.

Das Problem ist nicht, dass Entwickler Dokumentation nicht schätzen. Die meisten tun das. Das Problem ist, dass Dokumentation außerhalb der Rückkopplung der Softwareauslieferung liegt. Sie blockiert keinen CI-Build. Sie lässt keinen Test fehlschlagen. Sie kann unbegrenzt verschoben werden, ohne dass sofort etwas kaputtgeht.

Die Lösung entspricht der anderer manueller Prozesse: automatisieren. Mache die Neuerzeugung der Dokumentation zum Teil des Auslieferungsereignisses — zur Folge eines Code-Merges statt zu einer separaten Aufgabe im Backlog.

Die Pipeline zur Dokumentationsautomatisierung

CodeDoc AI for Confluence unterstützt vier Auslösertypen. Zusammen decken sie das gesamte Spektrum von manuellen Testläufen bis zu vollständig automatisierten Pipelines nach dem CI/CD-Prinzip ab:

Den passenden Auslöser wählen

Dein Auslöser bestimmt, wie häufig die Dokumentation neu erzeugt wird — und damit deinen KI-Tokenverbrauch. Hier ein praktischer Vergleich:

Webhook-Auslöser einrichten

Webhook-basierte Auslöser („On Commit“ und „On Merge“) funktionieren, indem du die Webhook-URL von CodeDoc AI bei deinem Git-Anbieter registrierst. Die App liefert eine einzige URL für alle Aufträge und Anbieter — anhand der eingehenden Repository-URL und des Branchs erkennt sie den auszuführenden Auftrag.

Die Webhook-URL erscheint bei Auswahl von „On Commit“ oder „On Merge“ — kopiere sie in die Webhook-Einstellungen deines Git-Anbieters

Schnelle Einrichtung je Anbieter:

• GitHub: Repository → Settings → Webhooks → Add webhook. Setze „Content-type“ auf application/json. Wähle „Just the push event“ für „On Commit“ oder „Pull requests“ für „On Merge“. Die vollständige Anleitung findest du unter docs.github.com.
• GitLab: Project → Settings → Webhooks. Aktiviere „Push events“ für „On Commit“ oder „Merge request events“ für „On Merge“.
• Bitbucket: Repository → Repository settings → Webhooks. Auslöser: „Repository Push“ für „On Commit“ oder „Pull Request Fulfilled“ für „On Merge“.
• Azure DevOps: Project settings → Service hooks → Create subscription → Web Hooks. Ereignis: „Code pushed“ oder „Pull request merged“.

Du musst den Webhook je Repository nur einmal registrieren — dieselbe URL verarbeitet alle Aufträge, die dieses Repository verwenden.

Geplante Dokumentation

Geplante Auslöser benötigen keine Webhook-Konfiguration. Drei Zeitplantypen sind verfügbar:

• Täglich — wähle die früheste UTC-Stunde. Die Ausführung erfolgt ungefähr innerhalb einer Stunde nach der konfigurierten Zeit.
• Wöchentlich — wähle Wochentag und früheste UTC-Stunde.
• Monatlich — wähle Monatstag (1–28) und früheste UTC-Stunde.

Geplante Auslöser sind der unkomplizierteste Weg zur Automatisierung. Kein Webhook und keine Git-Anbieter-Konfiguration erforderlich. Sie eignen sich gut für:

• Infrastruktur-Repositories (Terraform, Kubernetes, CloudFormation), die sich langsam ändern, aber für Audits aktuelle Dokumentation benötigen.
• Compliance-Dokumentation, die den Produktionsstand nach einem festen Zeitplan abbilden muss.
• Teams mit Monorepositories, bei denen Webhook-Ereignisse zu häufig sind, um bei jedem Push einen vollständigen Dokumentationsauftrag auszulösen.

Bevorstehende geplante Aufträge — nächste Ausführung und Countdown im Dashboard sichtbar

KI-Dateiauswahl: Dokumentation relevant halten

Eine der größten Einflussgrößen auf Qualität und Kosten der Dokumentation ist die Auswahl der Dateien für die KI. Ein ganzes Repository einschließlich Testdaten, erzeugter Dateien, Migrationsskripte und Lock-Dateien zu senden, vergräbt wichtige Inhalte in Nebensächlichem und verbraucht mehr Tokens als nötig.

Dateianalyse-Vorschau — geschätzter Tokenverbrauch und KI-ausgewählte Dateien vor der Ausführung

CodeDoc AI bietet mehrere Ansätze zur Dateiauswahl:

• Alle Dateien — jede Codedatei im Repository. Für kleine, gut strukturierte Repositories.
• KI-Auswahl (dynamisch) — die KI wählt bei jedem Durchlauf die relevantesten Dateien neu aus. Passt sich der Entwicklung der Codebasis an.
• KI-Auswahl (festgelegt) — die KI wählt einmal; du prüfst und fixierst die Liste. Vorhersagbare Tokenkosten bei späteren Durchläufen.
• Manuelle Auswahl — du wählst in der Analysevorschau die einzubeziehenden Dateien.
• Pfadfilter — beschränke die Analyse auf ein Unterverzeichnis (zum Beispiel /src oder /backend).
• Glob-Muster — schließe Dateien per Glob-Syntax ein oder aus. Schließe zum Beispiel **/*.test.ts aus, um Testdateien zu überspringen.

Der Freigabeprozess als Qualitätsprüfung

Vollautomatische Dokumentation funktioniert gut, wenn du der Ausgabe vertraust — das ist bei interner Entwicklerreferenzdokumentation vertretbar, die im Laufe der Zeit genutzt und korrigiert wird. Bei Dokumentation für einen größeren Leserkreis oder mit höheren Anforderungen solltest du vor der Veröffentlichung eine Prüfung einbauen.

Der Freigabeprozess in CodeDoc AI ergänzt einen menschlichen Prüfschritt, ohne die Automatisierung zu unterbrechen. Bei Aktivierung wird die erzeugte Dokumentation als Confluence-Entwurf mit dem Präfix [DRAFT] gespeichert. Der Auftrag läuft weiterhin nach Zeitplan oder Webhook-Auslösung — du veröffentlichst lediglich erst nach der Prüfung.

Praktische Aufteilung:

• Ohne Freigabe (vollautomatisch): Entwicklerdokumentation, Kurzreferenzen, Einarbeitungsanleitungen. Häufige Aktualisierung; gelegentliche Unvollkommenheiten sind vertretbar.
• Mit Freigabe: Kundendokumentation, Compliance- und Audit-Seiten, Managementübersichten. Seltener aktualisiert, vor Veröffentlichung geprüft.

Du legst das pro Auftrag statt global fest. In einem Confluence-Bereich können vollständig automatisierte und freigabepflichtige Aufträge gleichzeitig laufen.

Erzeugungsverlauf und Überwachung

Jede Dokumentationserzeugung wird in der Ansicht Erzeugungsverlauf (Generation History) protokolliert. Jeder Eintrag zeigt:

• Zeitstempel des Durchlaufs
• Verwendetes KI-Modell
• Anzahl analysierter Dateien
• Anzahl verbrauchter Tokens
• Status (erfolgreich / Entwurf wartet auf Freigabe / fehlgeschlagen)
• Direkter Link zur erzeugten Confluence-Seite

Erzeugungsverlauf — Aktivitätsdiagramme (7 Tage, 4 Wochen, 12 Monate) und Details einzelner Durchläufe

Die Verlaufsansicht enthält außerdem Aktivitätsdiagramme für 7 Tage, 4 Wochen und 12 Monate. Damit kannst du die Erzeugungshäufigkeit überwachen, unerwartete Spitzen erkennen (zum Beispiel einen falsch konfigurierten Webhook, der bei jedem Push auslöst) und den kumulierten Tokenverbrauch im Zeitverlauf verfolgen.

Ein vollständiges Automatisierungsbeispiel

So könnte ein mittelgroßes Entwicklungsteam eine vollständige Dokumentationspipeline für das Hauptrepository seiner Anwendung konfigurieren:

1. Auftrag für Entwicklerdokumentation — Auslöser: On Merge. Voreinstellung: Developer Documentation. Dateiauswahl: dynamische KI-Auswahl, mit Ausschluss von **/*.test.*. Freigabe: aus. Ziel: Confluence-Bereich Entwicklung → Seite „Service: [Repository-Name]“.
2. Auftrag für die Managementübersicht — Auslöser: wöchentlich geplant (Montag 09:00 UTC). Voreinstellung: Management Overview. Dateiauswahl: wie oben. Freigabe: an. Ziel: Confluence-Bereich Produkt → Seite „Systemübersicht: [Repository-Name]“.
3. Auftrag für die Einarbeitungsanleitung — Auslöser: monatlich geplant. Voreinstellung: Onboarding Guide. Dateiauswahl: Pfadfilter /src. Freigabe: an. Ziel: Confluence-Bereich Entwicklung → Seite „Einarbeitung: [Repository-Name]“.

Ein Repository, drei Aufträge und drei Confluence-Seiten für drei unterschiedliche Zielgruppen — alle automatisch gepflegt, ohne dass jemand Dokumentation von Hand schreibt.

Häufig gestellte Fragen