Ein Jira-Projekt automatisch dokumentieren: Von manuellen Updates zu lebendiger Dokumentation

Warum Jira-Projekte undokumentiert bleiben

In den meisten Entwicklungsteams liegt die Arbeit in Jira — Tickets, Epics, Sprints und Historie. In Confluence soll die Dokumentation liegen — Architekturentscheidungen, Betriebsanleitungen, API-Referenzen und Einarbeitungsanleitungen. In der Lücke dazwischen geht Wissen verloren.

Entwickler schließen Jira-Tickets. Niemand aktualisiert die Confluence-Seite. Drei Monate später liest ein neues Teammitglied die Dokumentation zur „aktuellen Architektur“ und arbeitet mit Annahmen, die schon in Sprint 14 nicht mehr stimmten. Jedes Team mit beiden Werkzeugen kennt das.

Die Ursache ist nicht Vernachlässigung, sondern Reibung. Beim Schließen eines Tickets ist Dokumentationspflege immer optional. Sie erfordert ein zweites Werkzeug, die Suche nach der richtigen Seite und Kontext, der sich wiederholend anfühlt, wenn das Jira-Ticket die Änderung schon beschreibt. Automatisierung beseitigt diese Reibung, indem vorhandene Arbeitsereignisse Dokumentationsereignisse auslösen.

Die drei Dokumentationsebenen

Die meisten Teams brauchen alle drei. Ebene 1 ist in fünf Minuten eingerichtet und beantwortet „Was ist der aktuelle Status?“. Ebene 2 braucht 30 Minuten und beantwortet „Was hat sich in diesem Sprint verändert?“. Ebene 3 benötigt eine Stunde zur Konfiguration und beantwortet „Was macht diese Codebasis eigentlich?“.

Ebene 1 — Aktuelle Vorgangsmakros in Confluence

Mit dem in Confluence Cloud integrierten Jira-Vorgangsmakro bettest du eine aktuelle Vorgangstabelle auf jeder Confluence-Seite ein. Sie liest eine JQL-Abfrage aus und aktualisiert sich automatisch — du musst die Seite nicht bearbeiten, wenn neue Tickets oder Statusänderungen hinzukommen.

Eine einfache Projektdokumentationsseite könnte enthalten:

• Ein Jira-Vorgangsmakro mit dem Filter project = PROJ AND status != Done ORDER BY created DESC — zeigt das aktive Backlog auf einen Blick
• Ein zweites Makro für offene Bugs: project = PROJ AND issuetype = Bug AND status != Done
• Ein drittes Makro für den aktuellen Sprint: project = PROJ AND sprint in openSprints()

Das Ergebnis: eine Confluence-Seite, die ohne Eingriffe aktuell bleibt. Entwickler und Stakeholder sehen den aktuellen Projektstand — keine Momentaufnahme von vor zwei Wochen.

Einzelne Jira-Vorgänge mit Confluence-Seiten verknüpfen

Verknüpfe bei einzelnen komplexen Funktionen den Jira-Vorgang direkt mit seiner Spezifikationsseite in Confluence. Öffne den Vorgang in Jira und nutze den Abschnitt „Confluence-Seiten“, um eine Seite zu verknüpfen oder zu erstellen. Die Verknüpfung erscheint im Vorgang (für alle sichtbar, die das Ticket ansehen) und in Confluence (mit dem zugehörigen Jira-Vorgang).

Öffnet ein Entwickler ein Jira-Ticket für seine Umsetzung, ist die verknüpfte Spezifikation einen Klick entfernt. Öffnet ein Produktmanager die Confluence-Spezifikation, sieht er den aktuellen Vorgangsstatus ohne Werkzeugwechsel.

Ebene 2 — Automatisch erzeugte Sprint-Zusammenfassungen

Jira Automation kann beim Sprintabschluss eine Confluence-Seite erstellen oder aktualisieren. Eine einfache Regel sieht so aus:

• Auslöser: Sprint abgeschlossen
• Aktion: Confluence-Seite im Projektbereich erstellen, mit dem Sprintnamen als Titel
• Inhaltsvorlage: Abgeschlossene Vorgänge (aus Smart Values), begonnene, aber nicht abgeschlossene Vorgänge und Sprintdaten

Nach der Ersteinrichtung erstellt jeder Sprintabschluss automatisch eine dokumentierte Sprint-Zusammenfassung in Confluence — niemand muss mehr ans Schreiben denken. Nach sechs Monaten hast du eine vollständige Historie dessen, was wann ausgeliefert wurde.

Ebene 3 — KI-generierte Codedokumentation mit CodeDoc AI

Das schwierigste Dokumentationsproblem von Entwicklungsteams sind nicht Sprint-Zusammenfassungen, sondern technische Dokumentation: Architekturdiagramme, API-Referenzen, Beschreibungen von Datenmodellen und Einarbeitungsanleitungen. Sie erfordern Schreibkompetenz, technische Präzision und Aktualität. Gleichzeitig sind sie manuell am teuersten zu erstellen und veralten am wahrscheinlichsten.

CodeDoc AI for Confluence verbindet dein GitHub- oder GitLab-Repository mit Confluence und erzeugt automatisch technische Dokumentation. Bei jedem Push auf einen konfigurierten Branch liest die App die geänderten Dateien, erzeugt mit deinen Voreinstellungen Dokumentation und aktualisiert die entsprechende Confluence-Seite.

Das Ergebnis: Deine Confluence-Seite „Codebasis-Übersicht“ wird bei jeder Codeänderung neu erzeugt. Entwickler müssen nicht an Dokumentationspflege denken — die Dokumentation folgt dem Code.

CodeDoc-AI-Dashboard — Dokumentationsaufträge verbinden dein GitHub-Repository mit Confluence-Seiten, automatisch bei jedem Push ausgelöst

Dokumentation von GitHub nach Confluence einrichten

1. 1
   Installiere CodeDoc AI for Confluence aus dem Marketplace. Es ist eine Forge-App — ohne externe Server, innerhalb von Atlassians Infrastruktur.
2. 2
   Verbinde dein GitHub- oder GitLab-Repository. Füge ein persönliches Zugriffstoken mit Lesezugriff auf das Repository hinzu. CodeDoc AI liest deine Repository-Dateien — es schreibt nie in dein Repository.
3. 3
   Konfiguriere einen Dokumentationsauftrag. Wähle die einzubeziehenden Dateien (zum Beispiel src/**/*.ts), eine Dokumentationsvoreinstellung (Codebasis-Übersicht, API-Referenz, README) und die Confluence-Zielseite für die Ausgabe.
4. 4
   Setze den Auslöser. Führe die erste Erzeugung bei Bedarf aus. Aktiviere anschließend den Webhook-Auslöser, damit bei jedem Push auf deinen Hauptbranch automatisch neu erzeugt wird.
5. 5
   Prüfe und verbessere die Ausgabe. Lies die erste erzeugte Seite und prüfe die Voreinstellung. Häufige Anpassungen: die Dateiauswahl eingrenzen, um Testdateien auszuschließen, und einen eigenen Prompt für einen bestimmten Aspekt ergänzen (zum Beispiel „Dokumentiere nur die öffentliche API-Oberfläche“).

Eine vollständige Anleitung mit Screenshots findest du hier: Confluence-Dokumentation automatisch aus GitHub erzeugen.

CodeDoc-AI-Aufträge — jeder Auftrag verbindet einen oder mehrere Repository-Pfade mit einer Confluence-Seite und konfigurierbaren Auslösereinstellungen

Empfohlene Confluence-Struktur für ein Jira-Projekt

Ein gut organisierter Projektbereich in Confluence spiegelt die natürliche Struktur eines Jira-Projekts wider. Ein Bereich je Team oder Produktgebiet, mit Unterseiten für:

• Projektübersicht — aktuelles Jira-Vorgangsmakro sowie wichtige Entscheidungen und Ziele (von Menschen geschrieben, selten verändert)
• Architektur und Codebasis — von CodeDoc AI erzeugt, automatisch aktualisiert
• Sprint-Historie — eine Unterseite pro Sprint, beim Sprintabschluss automatisch von Jira Automation erstellt
• Entscheidungen — Architecture Decision Records (ADRs), manuell geschrieben, in einem schlanken Format
• Betriebsanleitungen — Betriebsleitfäden, von Entwicklern gepflegt und aus passenden Jira-Vorgangstypen verknüpft

Die zentrale Erkenntnis: Ebenen 1–3 pflegen automatisch die Seiten, die aktuell bleiben müssen. Von Menschen verfasste Seiten (Entscheidungen, Betriebsanleitungen) können manuell bleiben, weil sie sich selten ändern und Urteilsvermögen erfordern, das Automatisierung nicht bietet.

Codedokumentation vertraulich halten: BYOK-KI

Für Teams in regulierten Branchen ist das Senden von Quellcode an einen KI-Anbieter eine wesentliche Datenschutzfrage. CodeDoc AI unterstützt Bring Your Own Key (BYOK) — du konfigurierst deinen eigenen OpenAI- oder Anthropic-API-Schlüssel in den App-Einstellungen. Dadurch wird dein Code unter der Vereinbarung deiner Organisation mit dem KI-Anbieter verarbeitet, nicht über einen gemeinsamen Anbieterschlüssel.

Eine ausführliche Erklärung, warum das für Unternehmens- und Compliance-Teams wichtig ist, findest du hier: BYOK-KI für Atlassian: Was sie bedeutet und warum sie wichtig ist.

Häufig gestellte Fragen