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


Gerade erst letzte Woche sorgte ein Kraftakt von Anne und Richard mit Unterstützung von Moritz dazu, dass die Produktdokumentation wieder akzeptabel aktuell wurde. Sie konnten nach ihrer eigenen Einschätzung wichtiges Wissen sichern. Heute, gleich im Anschluss an das Weekly, bitten die beiden Moritz erneut um ein Gespräch. Thema ist wieder die Dokumentation.

« Wir haben den dreistufigen Prozess vom schnell geschriebenen Arbeitsdokument zum qualitativ hochwertigen Baustein im Wiki probiert. », beginnt Anne. « Wir sind damit nicht glücklich. »

Richard ergänzt: « Du hast vor langer Zeit gesagt, dass uns mit CARDS+ das Dokumentieren leichter fallen wird. Am Anfang war es auch so. Die Cases schreiben hat Spaß gemacht. War kreativ. Aber jetzt ist der Wurm drin. Das Schreiben von Services ist nur mehr lästig. »

Moritz schaut die beiden an und weiß nicht recht, was er sagen soll.

Anne bemerkt, dass sie Moritz kalt erwischt haben und erklärt, dass sie gerne mit ihm eine Idee durchsprechen wollen. « Aber wir haben keine fertige Lösung dafür. », schränkt sie sofort ein.

Die Idee ist schnell erklärt. Anne erzählt, sie wollen anstelle der Service-Seite im Wiki ein Asciidoc-Dokument schreiben und im Git-Repository speichern. Es hat den gleichen Aufbau mit Steckbrief, Beschreibung und dynamische und statische Sicht. « Asciidoc ist super integriert in IntelliJ. Auch Gitlab unterstützt es. Wir müssen nicht zwischen Wiki und Code wechseln. Asciidoc checken wir gemeinsam mit dem Code ein. Im Merge-Request prüfen wir dann auch diese Dokumente. »

Richard ergänzt: « Du hast uns vor einiger Zeit erzählt, dass ein Team Asciidoc verwendet, um Betriebsanweisungen zu schreiben. Das hat uns inspiriert. Und wir finden es gut. Besser als den Umweg über Arbeitsdokumente im Wiki. Die können wir uns komplett sparen. »

« Wollt ihr jetzt generell mit Asciidoc arbeiten, ohne Confluence? », fragt Moritz.

Annes Antwort kommt sofort: « Nein, soweit wollen wir nicht gehen. Aber als Ersatz für die Service-Seiten. Es fällt uns einfach leichter mit Asciidoc, die ganze Doku zu schreiben. »

« Wenn ich dich richtig verstehe, dann ist euer Vorschlag, in Confluence den Baustein Service nicht mehr zu verwenden. »

Anne und Richard nicken zustimmend.

Moritz überlegt einer kurzen Moment. « Das bedeutet aber, dass ich in den Essenzschritten der Lösung in einem Case nicht mehr mit einem Service verlinken kann, weil es die Seite in Confluence nicht mehr gibt. Ich würde dann einen Service einfach nur im Text erwähnen. Habt ihr euch das so gedacht? »

Jetzt brauchen Anne und Richard einen Moment Zeit zum Nachdenken. Schließlich antwortet Anne: « Es geht um eine Vereinfachung für uns. Was es für dich bedeutet, haben wir uns nicht überlegt. Wie gesagt, es ist ja nur eine Idee. »

Im weiteren Verlauf des Gesprächs wird klar, dass Moritz noch weitere wichtige Funktionen verlieren würde, wenn es keine Service-Seiten mehr gibt.

Mit dem Baustein Service bildet die Produktdokumentation unter anderem ein zentrales Namensverzeichnis. Jede Komponente, jeder Dienst bekommt einen eindeutigen Namen. Es gelingt so wesentlich einfacher, eine gewisse Linie in die Vergabe von Namen zu bekommen. Das Team macht sich schon beim Entwurf einer Komponente nicht nur Gedanken über die Realisierung, sondern auch über die Benennung. Der Name ist eindeutig, jedem Teammitglied geläufig. Ohne Service-Seiten fehlt diese Unterstützung eines ganz wichtigen Aspekts des Domain-Driven-Design, der gemeinsamen Sprache.

Neben der Verlinkung von Case und Service ist auch die Verlinkung eines Service mit den eingesetzten Technologien im Steckbrief nicht mehr möglich. Dadurch verliert Moritz eine wichtige Funktion für den Fall, dass aus lizenzrechtlichen oder anderen Gründen eine vom Team gewählte Technologie durch eine andere ersetzt werden muss. Das mag jetzt noch nicht kritisch sein. Spätestens ab dem Zeitpunkt der Wartung ist dieser Punkt sehr wichtig.

Auch der Komponentenüberblick hängt ohne Service-Seiten in der Luft. Aus der klickbaren Übersicht über die Systemstruktur wird ein eher unverbindliches Bild mit zweifelhafter Zukunft – zumindest was die Qualität betrifft. Das ist schade, weil Moritz den Komponentenüberblick sehr gerne und erfolgreich verwendet, um anderen Kollegen im Unternehmen die Umsetzungsidee des Reise-Butlers zu vermitteln. Gerade der Einsatz von Microservices und die lose Kopplung durch event-basiertes Streaming kann Moritz mit der Darstellung sehr gut erklären. Auch Verena konnte er mit der ersten Version des Komponentenüberblicks überzeugen, das Projekt Reise-Butler zu starten.

Die Beschreibung einer Schnittstelle basiert ebenfalls zu einem Teil auf dem Baustein Service. Provider und Consumer der Schnittstelle werden mit jeweils einer Service-Seite beschrieben. Der Punkt ist neu für die Studenten, aber Moritz war hier schon einen Schritt weiter. Denn für einen produktiven Einsatz des Reise-Butlers sind Schnittstellenvereinbarungen erforderlich. Dort werden sogenannte Service-Level-Agreements, kurz SLA, festgehalten. Solche SLA haben in der Regel Auswirkungen auf die Datenqualität sowie die Mengen und die Kosten für die Bereitstellung bzw. Verfügbarkeit der Daten. Auch das Thema Sicherheit spielt eine wichtige Rolle.

Der Baustein Service ist mehr als nur die Beschreibung der Geschäftslogik eines Dienstes. Es ist offensichtlich, dass sie entweder auf Asciidoc verzichten oder eine integrierte Lösung schaffen, die eine Verbindung von Asciidoc-Dokumenten im Git-Repository mit Seiten in Confluence herstellt. Moritz hat leider keine fertige Lösung parat, verspricht aber, sich Gedanken zu einer Lösung machen. Er würde aber gerne grobe Lösungsideen entwickeln, die für die Entwickler die gewünschte Erleichterung in der Pflege bringen und seine Bedürfnisse in der Nutzung der Produktdokumentation erfüllen. Dazu möchte Moritz heute eine Stunde im Teamwork benutzen und das ganze Team beteiligen.

Zuletzt veröffentlichte Beiträge: