Der Schmerz der manuellen Dokumentation

Die Dokumentation in der Software-Entwicklung ist für viele Teams nicht gerade die höchste aller Freuden. Es liegt in der Natur der Sache, dass sie sich lieber mit Code beschäftigen als mit dem administrativen und organisatorischen Drumherum.

Dennoch muss die Dokumentation eines Software-Produkts natürlich so lückenlos und vollumfänglich wie möglich erfolgen – einerseits um intern Transparenz und Sichtbarkeit für Stakeholder zu schaffen, andererseits um Kunden und User immer auf dem aktuellen Stand zu halten und ihnen wichtige Details zur Weiterentwicklung und zu neuen Funktionen an die Hand zu geben.

Kurz: Die Doku sollte möglichst mit der Entwicklung synchronisiert sein.

Automatische Doku von Jira-Inhalten in Confluence

Die App AutoPage ist angetreten, Teams einen Großteil der Schmerzen manueller Dokumentationsarbeit zu nehmen. Sie ermöglicht es nämlich, direkt aus Jira heraus automatisch Confluence-Seiten zu erstellen, auf denen die aktuellen Inhalte der Vorgänge dokumentiert sind. Auf diese Weise kann die in Jira organisierte Entwicklung mit der Doku in Confluence jederzeit synchron gehalten werden.

Klingt vielversprechend? Dann probiere AutoPage aus! Dieser Beitrag soll dich dabei unterstützen, denn in ihm gehen wir mal Schritt für Schritt die initiale Einrichtung der App durch. Wenn du diese Dinge erledigt hast, kann dein Team Jira wie gewohnt nutzen – mit dem Unterschied, dass die Weiterentwicklung nun automatisch in Confluence abgebildet wird.

Also los! Wir beginnen ganz am Anfang, nämlich bei der Installation von AutoPage.

Das Setup: zwei Apps und der Connection Wizard

Zunächst installierst du zwei Apps in deinen Atlassian-Systemen. Richtig gelesen, denn du benötigst einerseits die eigentliche AutoPage-App in Jira und musst andererseits eine Brücke zu Confluence schlagen. Das kleine Helferlein, das dafür verantwortlich ist, nennt sich AutoPage – Helper App für Confluence und ist kostenfrei. Diese musst du also zusätzlich in deiner Confluence-Instanz installieren.

Anschließend ist es nötig, die beiden Apps in deinen Systemen miteinander zu verbinden. Der entsprechende Prozess wird direkt bereitgestellt: Wenn du AutoPage zum ersten Mal startest (entweder aus dem linksseitigen Panel in einem Projekt heraus oder als Admin über den Manage Apps-Bereich), wird der Connection Configuration Wizard aktiv und führt dich durch die Verknüpfung. Damit sind die technischen Voraussetzungen für die Kommunikation zwischen Jira und Confluence gegeben.

Die Voraussetzungen: eine Confluence-Vorlage und eine Jira-Automatisierungsregel

Dann ist es Zeit für die erste Konfiguration. Durch sie stellst du sicher, dass dein Team später normal mit seinen Jira-Vorgängen arbeiten kann, während im Hintergrund die Issues und ihre Inhalte dokumentiert werden.

Im Grunde ist diese Vorbereitung ganz einfach, denn es braucht nur zwei Schritte, um mit der Automatisierung der Dokumentation zu starten. Du benötigst erstens ein Template in Confluence, das als Vorlage für die zu erstellenden Seiten dient. Und zweitens musst du in Jira eine AutoPage-Automatisierungsregel konfigurieren, die der App sagt, wann aus welchen Vorgängen Confluence-Seiten entstehen sollen.

Eine Confluence-Seite als Blaupause

Das initiale Confluence-Template ist eine normale Confluence-Seite, die als Blaupause für die spätere Doku zu verstehen ist – und du kannst dabei gerne die vollen Möglichkeiten des Confluence-Editors nutzen, um die Vorlagenseite ansprechend und übersichtlich zu gestalten.

Spannend wird es, wenn du die Platzhalter-Makros von AutoPage ins Spiel bringst: Mit ihnen legst du fest, wo welche Inhalte aus Jira erscheinen sollen. Um ein Makro einzufügen, tippe einfach / gefolgt von Autopage oder nutze das +-Icon im Menü des Editors.

Dabei hast du grundsätzlich die Wahl zwischen Inline- und Rich-Text-Makros. Bei Inline-Makros werden die Jira-Inhalte "inline" genau an den Stellen eingebunden, an denen ein entsprechendes Makro platziert ist. Rich-Text-Makros eignen sich wiederum für textlastige Elemente wie Vorgangsbeschreibungen; sie werden dann als tatsächlicher Text ausgegeben.

In der Autopage-Dokumentation zur Erstellung der Confluence-Vorlage findest du eine Übersicht aller aktuell verfügbaren Makros, darunter Vorgangstyp, Vorgangspriorität, Fertigstellungsdatum und viele mehr.

Eine AutoPage-Automatisierungsregel in Jira

Nachdem du die Confluence-Vorlage soweit fertiggestellt hast, solltest du dich der Jira-Instanz zuwenden, denn dort musst du nun eine oder mehrere Regeln definieren, die später die automatische Erstellung einer Confluence-Seite auslösen. In der AutoPage-App siehst du den Button Create rule, der den entsprechenden Erstellungsdialog initiiert.

Eine AutoPage-Regel besteht aus vier Elementen: einem Trigger-Ereignis als Auslöser, der Bedingung, die erfüllt sein muss, der Aktion, die daraufhin ausgeführt wird, sowie einigen Regeldetails.

Trigger

Diese Auslöser beziehen sich auf Ereignisse in Vorgängen. Welche Aktion oder welche Aktionen sollen die Seitenerstellung initiieren? Das legst du in diesem Schritt fest, wobei du mehrere Trigger kombinieren kannst. Die folgenden Ereignisse können als Trigger verwendet werden:

• Vorgang erstellt
• Vorgang aktualisiert
• Vorgang zugewiesen
• Vorgang erwähnt
• Vorgang kommentiert

Technisch versierte Admins haben auch die Möglichkeit, via REST-API eingehende Webhooks als Trigger zu definieren.

Condition

Da dein Team höchstwahrscheinlich nicht pauschal aus sämtlichen Vorgängen im Jira-System automatisch Confluence-Seiten generieren will, musst du anschließend bestimmte Konditionen festlegen, also Eingrenzungen vornehmen. Bei einer Condition handelt es sich um einen Filter, der auf Basis bestimmter Kriterien festlegt, welche Vorgänge die Regel auslösen sollen. Hierfür verwendest du die Jira Query Language (JQL), die es dir erlaubt, sehr präzise Eingrenzungen zu definieren (siehe hierzu die offizielle Atlassian-Dokumentation zur Verwendung der JQL).

Du möchtest zum Beispiel, dass nur Vorgänge eines bestimmten Projekts und eines bestimmten Vorgangstypen automatisch Confluence-Seiten erstellen, etwa Vorgänge des Typs "Bug" in einem spezifischen Entwicklungsprojekt? Mit der JQL kannst du diese Bedingung akkurat formulieren.

Aktion

Schritt 3 der Regelkonfiguration dreht sich um die Frage, was wo passieren soll, wenn ein Trigger in einem per Condition definierten Vorgang ausgelöst wird. Konkret: Wie soll die zu generierende Confluence-Seite heißen, auf welcher Vorlage soll sie basieren und wo soll sie entstehen?

Für die Seitentitel kannst du gewöhnlichen Text oder dynamische Smart Values nutzen, um beispielsweise die Vorgangsschlüssel zu integrieren. Weiterhin definierst du hier die erforderlichen Confluence-Einstellungen: Du gibst den Bereich, in dem sich die Vorlage befindet, sowie die Vorlage selbst an und benennst für die Erstellung der neuen Seiten den gewünschten Bereich und die übergeordnete Seite im Seitenbaum.

Letzte Details

Schließlich sind nur noch ein paar Kleinigkeiten zu klären. Die Regel braucht einen Namen und empfehlenswerterweise eine kurze Beschreibung, die ihren Zweck deutlich macht. Darüber hinaus kannst du die Regel aktivieren oder deaktivieren. (Du möchtest noch mehr Details? Alle Infos zu den Autopage-Automatisierungsregeln mit ihren Triggern, Conditions und Aktionen findest du in der Doku zur App.)

Und das war’s schon – ein halbes Stündchen an administrativer Vorbereitung ist ein überschaubarer Preis dafür, dass dein Team ab jetzt die Doku mit der Entwicklung automatisch synchronisieren und signifikante Umfänge an manueller Arbeit einsparen kann, während die Stakeholder und User eures Produkts stets aktuelle Informationen zur Weiterentwicklung haben, oder?

AutoPage steht auf dem Atlassian Marketplace bereit. Du kannst die App kostenfrei und unverbindlich auf Herz und Nieren testen! Hast du Fragen zur Lösung? Willst du mehr über die Anwendungsfälle oder Potenziale wissen? Dann melde dich bei uns oder vereinbare direkt einen Demotermin: Das Entwicklungsteam freut sich darauf, mit dir ins Gespräch zu kommen!

Weiterführende Infos

AutoPage goes Cloud – die einfachste Lösung für dein Doku-Problem
Fünf Aspekte, wie Agile Hive mit Atlassian Jira die SAFe-Transition unterstützt
Die Übersichts-Dokuseite für AutoPage