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


Die eine Stunde Ideensammlung und Recherche im Internet gestern im Teamwork zusammen mit dem Team waren für Moritz sehr inspirierend. Gemeinsam haben sie diskutiert, im Internet recherchiert und Lösungsideen bewertet. Eine für ihre Bedürfnisse passende Lösung konnten sie jedoch nicht finden. Heute will Moritz sich Zeit nehmen, einige interessante Ansätze zu vertiefen, die sie gestern bestenfalls gestreift haben.

Ganz spannend findet Moritz den Ausdruck “Documentation as Code” (kurz DaC). Klingt ganz ähnlich wie “Infrastructure as Code” (kurz IaC), manchmal auch als „programmierbare Infrastruktur“ bezeichnet. Mit IaC wird der Aufbau und die Konfiguration der Infrastruktur in einem Softwareentwicklungsprojekt programmiert. Im Kern stellt IaC einen Wandel von manuellen Tätigkeiten hin zu automatisierten Abläufen dar. Am wichtigsten ist jedoch das Konzept der Reproduzierbarkeit mit dem Ziel, die Qualität zu verbessern und die Effizienz beim Aufbau von Infrastrukturen zu erhöhen. DaC überträgt die Philosophie von IaC auf das Schreiben von Dokumentation. Das bedeutet, Dokumente werden mit den Werkzeugen der Entwickler geschrieben, besser gesagt entwickelt. Mit Markdown oder Asciidoc stehen geeignete Textformate für Dokumente zur Verfügung, um sie wie Code in Git zu speichern, zu prüfen  (z.B. mit Merge-Requests) und zusammen mit dem Code in Branches zu organisieren. Fehler in der Dokumentation werden wie Fehler im Code behandelt und genau so gelöst. Im Zusammenhang mit ARC42, einem vorlagenbasierten Ansatz zur Dokumentation von Software-Architekturen, findet Moritz die docToolchain, eine Implementierung von “Documentation as Code” mit Groovy und ARC42 als Struktur für die Ablage der Dokumente in Git.

Weiterlesen auf github.com

Moritz vergleicht die Zielsetzung der docToolchain mit CARDS+. Beide Ansätze wollen die Qualität der Dokumentation erhöhen und gleichzeitig den Aufwand für die Pflege minimieren.

In docToolchain dreht sich alles um Asciidoc. Es gibt eine ganze Reihe von vordefinierten Exportern, die Ergebnisdokumente aus verschiedenen Quellen in Asciidoc konvertieren. Weitere Exporter können mit Groovy realisiert werden. Die Verantwortung für die Dokumentation liegt damit weitestgehend beim Team, der Product-Owner kann nur eingeschränkt mitarbeiten und muss die Werkzeuge der Entwickler verwenden. Eine echte Herausforderung. Im Kern von docToolchain werden alle exportierten Asciidoc-Dokumente zu einer Gesamtdokumentation kombiniert. ARC42 bildet den Rahmen mit einer Struktur, die für die Beschreibung der technischen Aspekte eines Software-Produktes optimiert ist. Vorlagen für eine Lösungsstrategie, Bausteinsicht, Laufzeitsicht, Verteilungssicht, Realisierungskonzept oder Entwurfsentscheidung sind wichtige Bestandteile von ARC42.

Moritz hat nun eine Vorstellung, wie docToolchain die “programmierbare Dokumentation” realisiert. « Aber was ist mit der fachlichen Perspektive », fragt er sich. Zumindest findet er keine entsprechenden Hinweise in docToolchain. Und ARC42 legt seinen Fokus ebenfalls auf die technischen Aspekte.

docToolchain verwendet Confluence nur zur Veröffentlichung der Gesamtdokumentation. Es ist offensichtlich nicht vorgesehen, die umfangreichen Möglichkeiten von Confluence für verteiltes Arbeiten im Team zu nutzen. Feedback der Leser in Confluence durch Kommentare kann nicht genutzt werden. Die inhaltliche Arbeit für die Dokumentation findet nur im Code und in Werkzeugen wie EA, Visio, Powerpoint oder Excel statt. Für jedes Werkzeug muss die Zusammenarbeit im Team geregelt werden. Moritz hat aus leidvoller Erfahrung gelernt, dass sich gerade bei Powerpoint oder Excel verteiltes Arbeiten im Team immer noch schwierig gestaltet.

Moritz weiß, dass CARDS+ hier einen anderen Weg beschreitet. Das Produkt wird ganzheitlich in einem Wiki beschrieben. Feedback durch moderierte Kommentare ist ein wichtiges Qualitätsmerkmal. Die Produktdokumentation wird modular mit Bausteinen aufgebaut. Mit der Systembeschreibung wird das Produkt aus der fachlichen Perspektive betrachtet, vom Groben ins Feine mt einem Übergang in die Technik. Der Baustein Topic hilft bei der Abgrenzung des Produktes. Es legt gleichzeitig den Problemraum (englisch scope) des Produktes fest und nimmt Bezug auf die Geschäftsprozesse, in denen das Produkt verwendet wird. Ein Topic wird vom Product-Owner erstellt, in der Sprache der Stakeholder. Für die weitere Gliederung gibt es den Baustein Epic. Es beschreibt einen konkreten gut abgrenzbaren Aufgabenbereich im Produkt. Jedes Epic wird schließlich mit dem Baustein Case in seine einzelnen Aufgaben oder Funktionen zerlegt. Ein Case ist immer zweiteilig. In der Ausgangslage wird das fachliche Problem beschrieben, das es zu lösen gilt. Die Lösung bildet dabei den Übergang in die Technik.

Bei der Beschreibung der technischen Aspekte sind sich CARDS+ und ARC42 sehr ähnlich. Es gibt Bausteine für Entscheidungen, Schnittstellen und Komponenten. In der Umsetzung erkennt Moritz aber wesentliche Unterschiede.

docToolchain orientiert sich komplett an der Struktur von ARC42. Die Werkzeugkette mit Asciidoc, Pandoc und Groovy-Skripten erzeugt aus manuell zu erstellenden Eingangsdokumenten und einem Asciidoc-Rahmen vollautomatisch eine integrierte Beschreibung des Produktes.

CARDS+ unterscheidet Systemstruktur und Architekturentwurf. Der Architekturentwurf ist eine Sammlung fundamentaler Entscheidungen und übergreifender Konzepte. Die Systemstruktur bildet ein Verzeichnis von Komponenten und deren Schnittstellen mit den Bausteinen Service, Entity und Event. Gruppiert werden sie mit dem Baustein Domain. Die Verbindung von Dokumentation im Wiki mit dem Code im Git-Repository wird durch die Namen hergestellt. Im Wiki wird erfasst, was nicht oder nur sehr schwer aus dem Code ablesbar ist. Damit ist der Code Teil der Dokumentation. Testfälle bilden einen weiteren wichtigen Teil der Dokumentation. Die Produktdokumentation existiert dadurch im Wiki und im Git.

Moritz findet “Documentation as Code” sehr spannend. docToolchain und ARC42 ist Moritz aber zu stark fokussiert auf die Beschreibung der technischen Aspekte, es fehlt ihm die fachliche Perspektive. Seiner Ansicht nach löst docToolchain nicht die Probleme der Pflege der Produktdokumentation, sondern automatisiert lediglich das Zusammenführen zu einer Gesamtdokumentation und das Veröffentlichen in verschiedenen Ausgabemedien, u.a. Confluence oder PDF.

Moritz ist weiterhin von der Wirksamkeit von CARDS+ überzeugt. Mittlerweile glaubt er, mit “Documentation as Code” auch CARDS+ verbessern zu können. Speziell der Wunsch der Studenten, ihren Beitrag zur Produktdokumentation mit Asciidoc zu leisten, ist ein wichtiger Treiber für Moritz. Eine zufriedenstellende Lösung hat Moritz aber auch heute nicht gefunden.

Zuletzt veröffentlichte Beiträge: