Der Reise-Butler ist die Smartphone-App für den wissbegierigen Reisenden und Fallbeispiel für die Methode CARDS+.


Gestern lag der Fokus von Moritz’ Recherchen auf der Umsetzung von “Documentation as Code” durch docToolchain und ARC42. Heute will er schauen, ob es nicht doch eine vergleichbare Lösung gibt, die auf die Stärken von Confluence setzt. Moritz will auf die Möglichkeiten eines Wiki für verteiltes Arbeiten im Team, auf die Volltextsuche, die Verlinkung von Seiten und die Nutzung von Stichworten in den Seiten nicht verzichten. Die Kommentarfunktion für das Einsammeln von Feedback aller Leser der Dokumentation ist für ihn ebenfalls sehr wichtig. Kommentare sind seine einzige objektive Metrik zur Beurteilung der Qualität und des Fertigstellungsgrades einer Seite.

Eine Suche im Marketplace von Atlassian mit den Begriffen “documentation asciidoc” liefert genau einen Treffer: Das Addon Git4C.

Git4C ist ein Confluence-Addon zur Anzeige von Dateien in einem Git-Repository in einer Confluence-Seite. Die Integration basiert auf der Verwendung von Makros. Ein Makro realisiert einen Git-Browser, der Dateien mit Code oder Dokumente in den Formaten Markdown, PlantUML und Asciidoc direkt in der Seite anzeigt. Ein weiteres Makro zeigt den Inhalt einer einzelnen Datei an.

Weiterlesen auf opensource.networkedassets.com

Der Hersteller von Git4C veröffentlicht einen Confluence-Bereich, in dem die Funktionalität anhand der Dokumentation für das Produkt selbst gezeigt wird. Git4C kann u.a. Asciidoc-Dokumente in Confluence anzeigen und schließt so eine Lücke in den Lösungsansätzen von gestern. Aber der Medienbruch bleibt bestehen, ein Leser braucht weiterhin gleichzeitig Zugriff auf Confluence und Gitlab. Moritz erkennt sofort die für ihn gravierende Einschränkung: Keine Anzeige unterwegs, weil Gitlab nicht im Internet erreichbar ist.

Während Moritz so über die Chancen und Risiken beim Einsatz von Git4C nachdenkt, entsteht bei ihm ein neuer Gedanke. « Es muss doch möglich sein, ein Makro in Confluence zu realisieren, das eine Asciidoc-Datei im Anhang einer Seite anzeigt. So wie das PDF-Makro. », bringt Moritz seinen Gedanken auf den Punkt.

Moritz’ neue Idee basiert auf zwei Fundamenten. Zum Einen ist es das Confluence-Makro, zum Anderen ein Gradle-Plugin zur Übertragung von beliebigen Dateien aus dem Git-Repository in den Anhang einer Confluence-Seite. Damit sieht sich Moritz in der Lage, eine CI-Pipeline zu bauen für die Veröffentlichung eines Asciidoc-Dokumentes in Confluence. Die Service-Seite mit dem Steckbrief bildet den Anker in der Produktdokumentation, das Asciidoc-Dokument im Anhang steuert die Beschreibung und wichtige Details der Realisierung bei. Dadurch ist zum Lesen einer Confluence-Seite kein Zugriff auf Gitlab notwendig. Alle Inhalte kann ein Leser auch unterwegs lesen. Das Gradle-Plugin lädt eine neue Version einer Datei genau dann hoch, wenn der Code und alle anderen Bestandteile der Komponente im Git-Repository freigegeben werden, z.B. in einem Merge-Request in Gitlab.

Zunächst prüft Moritz die Machbarkeit des Confluence-Makros. Er findet schnell ein Tutorial des Herstellers von Confluence. Offensichtlich ist es recht einfach, ein Hello-World-Makro zu implementieren. Das gewünschte Makro zur Anzeige einer Datei im Anhang sollte daher ebenfalls machbar sein. Asciidoc ist ein bekanntes Format. Es gibt frei nutzbare Software, um Asciidoc in andere Formate zu konvertieren. Das zeigen docToolchain und Git4C recht eindrucksvoll. Speziell Git4C bietet bereits ein Makro, mit dem eine Asciidoc-Datei in einer Confluence-Seite angezeigt wird. Ein Blick in den Code der öffentlich zugänglichen Git-Repositories bestätigt Moritz in dieser Annahme.

Danach denkt Moritz über das Gradle-Plugin nach. Die Herausforderung und große Unbekannte ist mit Sicherheit der Zugriff auf Confluence. Die gute Nachricht ist, dass Confluence ein sehr umfangreiches REST-API anbietet. Die vorangegangenen Recherchen haben Moritz gezeigt, dass eine Realisierung möglich ist. Er möchte das Gradle-Plugin so gestalten, dass es flexibel nutzbar ist und gut in einer CI-Pipeline integriert werden kann. Es soll dateibasiert arbeiten, d.h. im Gradle-Skript werden Paare gebildet aus einer beliebigen Datei und einer Confluence-Seite. Das Gradle-Plugin soll keine Einschränkungen hinsichtlich der Dateiformate machen. Natürlich geht es vorrangig um Asciidoc-Dokumente. Aber auch eine Avro-Schema-Datei zur Spezifikation eines Events oder ein Skript zum Erzeugen einer Datenbanktabelle sind Kandidaten für eine Veröffentlichung in der Produktdokumentation.

Einen besonderen Vorteil sieht Moritz in der Paarbildung im Gradle-Skript. Durch die Verknüpfung der Confluence-Seite mit der Datei im Git-Repository wird sichergestellt, dass die Dokumente in Git und Confluence zusammenpassen. Wenn die Seite nicht mehr existiert, muss das Gradle-Plugin einen Fehler signalisieren, um die CI-Pipeline scheitern zu lassen. So wird zum richtigen Zeitpunkt eine Unstimmigkeit zwischen Produktinkrement und Produktdokumentation erkannt. Zur Korrektur kann eine neue Seite in Confluence verknüpft werden (z.B. wegen einer Neuordnung der Dokumentation) oder die Datei wird nicht mehr gebraucht, weil die Komponente nicht mehr produktiv im Einsatz ist und die Service-Seite endgültig aus der Produktdokumentation entfernt wurde.

Mit der Realisierung einer CI-Pipeline, die eine aktuell gültige Dokumentation in die Produktdokumentation in Confluence hochlädt, bekommen die Bausteine der Systemstruktur eine neue Qualität. Die Systemstruktur folgt immer dem Code. Service-Seiten werden von Moritz als Hülle angelegt, sobald er gemeinsam mit dem Team Entscheidungen zum Namen und zur verwendeten Technologie getroffen hat. Diese Entscheidungen kann er sofort festhalten. Er kann selbständig den Komponentenüberblick pflegen. Alle weiteren Details kommen aber vom Team. Die Entwickler schreiben ihren Teil der Dokumentation ohne Medienbruch mit den gewohnten Werkzeugen, die sie auch zum Entwickeln von Code oder Testfällen nutzen. Weil die Dokumentation in der gleichen CI-Pipeline integriert und freigegeben wird, wird sichergestellt, dass Code, Testfälle und Wiki für ein Produktinkrement stimmig sind. Code und Testfälle liegen geprüft und funktionsfähig im master-Branch im Git-Repository. In Confluence befindet sich passend zum master-Branch die Produktdokumentation.

Moritz kann in seiner Rolle als Analyst für die Anforderungen seine Ergebnisse mit den Bausteinen Topic, Epic und Case formulieren. Ein Case bleibt jedoch unvollständig, d.h. die Lösung hat noch keine Essenzschritte. Aus diesem Grund stellt es auch kein Problem dar, wenn die Systembeschreibung im Gegensatz zur Systemstruktur der Realisierung weit voraus ist. Der Problemraum ist unabhängig von der Realisierung, die beschriebenen fachlichen Aufgabenstellungen gibt es auf jeden Fall. Sie haben im aktuellen Produktinkrement aber keine Lösung.

Die Herausforderung für Moritz ist daher, die Essenzschritte passend zu den Fortschritten des Teams zu aktualisieren. Erst durch die Realisierung wird die Lösung in einem Case klar. Weil aber die Essenzschritte wie der Name schon sagt nur die “Essenz” der Lösung beschreiben sollen, reichen in jedem Schritt oft nur wenige kurze Sätze zur Erläuterung und Einordnung. Der wichtige Punkt ist aber die Verlinkung des Case mit anderen Seiten der Systemstruktur. Das ist aber jederzeit möglich, weil mindestens die Hülle der Seite mit dem Steckbrief immer vorhanden ist.

Moritz ist jetzt überzeugt, eine tragfähige und realisierbare Lösung zu haben. Sie erfüllt seiner Meinung nach alle Anforderungen, die Anne und Richard als Entwickler formuliert haben. Auch seine Bedürfnisse in seinen Rollen Produkt-Owner und Analyst werden weiterhin erfüllt. Er beschließt, sich an Verena zu wenden, um ihr den Vorschlag zu machen, die notwendigen Makros in Confluence und das Gradle-Plugin selbst zu implementieren.

Zuletzt veröffentlichte Beiträge: