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


Nach der Mittagspause treffen sie sich zum Teamwork. Wie von Moritz vorgeschlagen wollen sie gemeinsam Lösungsideen entwickeln, wie ein Asciidoc-Dokument im Git-Repository mit der Beschreibung eines Services und eine Service-Seite in Confluence kombiniert werden können. Eine Gemeinsamkeit haben alle Ansätze: Moritz kann weiterhin in Confluence mindestens den Steckbrief und die Stichworte so pflegen, wie er es jetzt auch tut. Nur so kann er die Möglichkeiten von Confluence voll ausschöpfen.

Für einen Überblick über den Lösungsraum starten sie mit einer Themensammlung, begrenzt auf eine Timebox von 15 Minuten.

Zunächst tauschen sie sich über die Vorteile von Asciidoc aus. Für Moritz unterscheiden sich Asciidoc, Markdown oder Confluence Wiki Markup nicht in ihrer Zielsetzung. Auch die Möglichkeiten zur Gestaltung sind praktisch identisch. Aus der Perspektive der Entwickler ist das Format optimal. Asciidoc lässt sich einfach und schnell schreiben. Die Unterstützung durch IntelliJ ist ausgezeichnet. In einem Merge-Request läßt sich eine Asciidoc-Datei wie jede andere Datei vergleichen und kommentieren. Asciidoc wird neben dem hauseigenen Markdown und RDoc von Gitlab generell sehr gut unterstützt.

Gitlab nutzt das sogenannte Gitlab Flavored Markdown (kurz GFM). GFM erweitert CommonMark um Autolinking, besseres Syntax Highlighting und erlaubt die Verwendung von Emojis. GFM nutzt Zeilenumbrüche im Text nicht zwingend als Umbrüche in der Darstellung.

Weiterlesen auf gitlab.com

Confluence unterstützt Wiki Markup bei der Eingabe im Editor. Alle Eingaben werden sofort in das interne Format übersetzt. Wiki Markup kann daher nachträglich nicht mehr geändert werden – es existiert nicht mehr in dieser Form.

Weiterlesen auf atlassian.com

Bei Copy&Paste sind sich alle einig, dass es keine Idee ist, die sie vertiefen müssen. Sollten sie keine andere Lösung finden, können sie Asciidoc-Dokumente manuell aus dem Git-Repository in die Confluence-Seite übertragen. Es ist dann einfach eine weitere Bedingung für die Definition von “Fertig” für ihr Produktinkrement.

Eine weitere Idee, die direkte Verwendung von Asciidoc in Gitlab und Confluence, können sie nach einer kurzen Recherche im Internet ebenfalls schnell abhaken. Confluence bietet keinerlei Unterstützung für Asciidoc. Auch die Suche nach Erweiterungen für Confluence, die Asciidoc unterstützen, bleibt vorerst erfolglos. Eine direkte Integration eines Asciidoc-Dokumentes im Git-Repository in einer Confluence-Seite scheint daher auf den ersten Blick unmöglich zu sein.

Die nächste Idee scheint aber vielversprechend zu sein. Gitlab übernimmt die Aufgabe, die Asciidoc-Dokumente in HTML zu rendern und als URL aufrufbar zur Verfügung zu stellen. In der Confluence-Seite für einen Service wird der Gitlab-Link direkt nach dem Steckbrief anstelle der weiteren Abschnitte eingefügt. Klingt im ersten Moment einfach.

Aber so schnell die Idee geboren wurde, so schnell erkennen sie auch gravierende Nachteile. Um die Dokumentation vollständig lesen zu können, muss ein Leser sowohl in Confluence als auch im Gitlab angemeldet sein. Gitlab ist derzeit aber auf das Intranet beschränkt. Für Moritz bedeutet das eine spürbare Einschränkung, wenn er unterwegs ist. Er kann dann zwar weiterhin alle Confluence-Seiten lesen, aber die Gitlab-Seite kann er nicht mehr öffnen. Eine weitere Randbedingung ist, dass die Zugangsberechtigung eines Lesers in beiden Systemen identisch ist. Gibt es einen Unterschied, dann kann der Leser zwar die Confluence-Seite öffnen, die Gitlab-Seite aber nicht.

Bei der Lösung müssen sie außerdem beachten, dass der Gitlab-Link sich immer auf einen Branch im Git bezieht. Derzeit ist es der “master”. Sollte irgendwann der Bedarf entstehen, einen anderen, komplexeren Git-Flow zu verwenden, dann bedeutet das eine Überarbeitung aller Seiten in Confluence mit einem Gitlab-Link. Das mag jetzt unkritisch erscheinen. Aber jetzt zu behaupten, die Situation wird sich nie ändern, ist ein eher nicht-agiler Gedanke. Der Gitlab-Link kann sich auch durch eine Änderung der Struktur des Codes im Git-Repository ändern. Der unerwünschte Seiteneffekt läßt den Gitlab-Link im Nirvana enden (HTML-Code 404).

Und ein letzter Punkt ist noch erwähnenswert. Es macht praktisch keinen Unterschied, einen Link oder den ganzen Inhalt aus Gitlab in die Confluence-Seite zu übertragen. Aber der zusätzliche Klick auf den Link, um den Inhalt in Gitlab lesen zu können, ist eher als Hürde zu sehen. Ein Medienbruch.

In Confluence gibt es eine Alternative zur Verlinkung von HTML-Seiten. Der Inhalt wird durch ein Makro direkt in die Confluence-Seite eingebettet. Ein zusätzlicher Klick ist nicht mehr notwendig. Aber der Medienbruch bleibt bestehen, ein Leser braucht gleichzeitig Zugriff auf Confluence und Gitlab. Es gibt aber einen entscheidenden Haken. Confluence ist im Internet erreichbar. Kein Administrator wird entgegen der Empfehlung von Atlassian die direkte Nutzung von HTML erlauben.

Das Confluence-Makro zeigt den Inhalt einer HTML-Webseite an. Das Makro muss zuvor durch einen Administrator für alle Bereiche aktiviert werden. Der Einsatz des Makros wird jedoch von Atlassian nicht empfohlen!

Weiterlesen auf atlassian.com

Die nächste Idee basiert auf der Möglichkeit, im Build-Prozess jedes Asciidoc-Dokument zusätzlich noch in ein anderes Datenformat zu konvertieren. Ein entsprechendes Gradle-Plugin ist vorhanden und kann sehr leicht integriert werden.

Das Plugin stellt einen neuen Task “asciidoctor” zur Verfügung. Der Task sucht in “sourceDir” nach Dateien mit der Endung “.adoc” (Standard), “.asciidoc”, “.ad” oder “.asc”. Das Plugin kann u.a. die Datenformate “html5”, “pdf”, “epub3” oder “docbook” erzeugen.

Weiterlesen auf github.com

Confluence kann eine PDF-Datei anzeigen. Bei dieser Lösung gibt es eine zusätzliche Herausforderung: Die PDF-Datei muss sich im Anhang einer Confluence-Seite befinden. Aber es gibt keinen Medienbruch mehr. Alle Inhalte sind in Confluence, ein Zugriff auf Gitlab ist für einen Leser nicht mehr erforderlich.

Das Confluence-Makro zeigt eine PDF-Datei im Anhang einer Seite wie eine Präsentation an. Leider hat Atlassian angekündigt, dass dieses Makro in zukünftigen Versionen von Confluence nicht mehr unterstützt wird.

Weiterlesen auf atlassian.com

Möglicherweise lässt sich das Hochladen der PDF-Datei in den Anhang einer Seite durch die Verwendung des REST-API von Confluence sogar automatisieren. Eine schnelle Recherche im Internet liefert auf jeden Fall Hinweise auf eine mögliche Realisierung.

Das Gradle-Plugin liest ein Markdown-Dokument und veröffentlicht es als Seite in Confluence. Zum Hochladen der Inhalte benutzt es das REST-API von Confluence.

Weiterlesen auf github.com

Das Gradle-Plugin liest ein Asciidoc-Dokument und veröffentlicht es als Seite in Confluence. Zum Hochladen der Inhalte benutzt es das REST-API von Confluence.

Weiterlesen auf github.com

Das Gradle-Plugin liest ein Swagger-Schema und veröffentlicht es als API-Dokumentation in Confluence. Zum Hochladen der Inhalte benutzt es das REST-API von Confluence.

Weiterlesen auf gitlab.slkdev.net

Leider zeigt Confluence generell bei der Integrationen von PDF-Dateien große Schwächen. Das Makro bietet keinerlei Optionen für die Darstellung der Vorschau in der Seite an. Für die Vollansicht ist ein weiterer Klick notwendig. Die Anzeige ist außerdem recht langsam. Insgesamt kann die Lösung mit der PDF-Datei niemanden im Team überzeugen.

Moritz muss auf die Timebox achten. Er fasst daher die bisher besprochenen Lösungsvarianten zusammen. Eine schnelles Blitzlicht zum Abschluss bestätigt Moritz’ Einschätzung, dass sie noch keine Lösung gefunden haben, die es Wert wäre, umgesetzt zu werden. In den verbleibenden Tagen dieser Woche möchte sich Moritz weiter mit dem Thema beschäftigen. Eine Entscheidung bezüglich Asciidoc müssen sie vorerst auf nächste Woche vertagen.

Allerdings bietet Moritz den Studenten die Copy&Paste-Variante an. Sie können unabhängig von seinen Recherchen überlegen, ob sie ihre Dokumentation mit Asciidoc schreiben wollen. Natürlich bedeutet es einen zusätzlichen manuellen Schritt, den Inhalt des Asciidoc-Dokumentes im Git-Repository aus der Gitlab-Seite in die Confluence-Seite zu kopieren. Dazu wünscht sich Moritz ebenfalls bis nächste Woche eine Entscheidung des Teams.

Zuletzt veröffentlichte Beiträge: