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


Das Produktinkrement macht Fortschritte. Das Team arbeitet sowohl an der Android-App als auch im Backend an der Datensammlung. Beim Weekly präsentiert Richard Ergebnisse der letzten Woche. Wie vereinbart zeigt er nicht nur die Implementierung (durch automatisierte Testfälle), sondern auch die Dokumentation im Wiki. Richard zeigt in jedem realisierten Case die Essenzschritte der Lösung und die dort verlinkten Seiten. Besonders in der Seite “Service PunktLoader” hebt er die Vollständigkeit der Dokumentation mit Sequenzdiagramm in der dynamischen Sicht und einem sehr detailliertem Klassendiagramm in der statischen Sicht hervor.

« Wow, da hast du dir ja echt viel Mühe gemacht bei der Beschreibung! » ist die erste Reaktion von Moritz.

Richard scheint das in der Antwort von Moritz nicht ausgesprochene «Aber» zu spüren und fragt: « Aber irgendwas habe ich vergessen, oder? »

« Nein, vergessen hast du nichts, soweit ich das jetzt auf die Schnelle beurteilen kann. Im Gegenteil … », antwortet Moritz vorsichtig.

Moritz hat ein Problem. Auf der einen Seite möchte er Anne und Richard loben, weil sie die Aufgaben so vorbildlich gelöst haben. Der Code ist lesbar, es gibt ausreichend Testfälle und speziell Richard hat sich sehr viel Mühe gemacht mit der Dokumentation. Mehr, als Moritz erwartet hat. Auf der anderen Seite sieht er aber ein Problem. Der Code wird seiner Einschätzung nach noch stark geändert werden. Er glaubt nicht, dass beispielsweise der im Sequenzdiagramm dargestellte Ablauf so bleiben wird. Kurz, er ist sich sehr sicher, dass die sehr detaillierten Diagramme noch häufig angepasst werden müssen. Er befürchtet, dass später diese Korrekturen nicht oder nur unvollständig gemacht werden. Das will er unbedingt ansprechen.

Aber nicht sofort. Moritz schließt zuvor das Weekly ab und gibt der anderen Arbeitsgruppe Gelegenheit, ihre Arbeit zu präsentieren. Dann, nach einer kurzen Pause, bittet er die Studenten um 15 Minuten ihrer Zeit: « Ich habe heute sehr viele gute Dinge gesehen. Das Produktinkrement nimmt Form an. Ihr achtet auf Qualität und schreibt Testfälle. Und ihr dokumentiert sehr ausführlich. Bei den Punkten eins und zwei macht bitte unbedingt weiter so. »

Die Studenten schauen sich überrascht an. Julius fragt nach: « Bei der Dokumentation nicht? »

Moritz überlegt kurz und antwortet: « Ja, in gewissem Sinn möchte ich, dass ihr beim Dokumentieren etwas ändert. Dafür muss ich aber etwas ausholen. »

In den folgenden Minuten versucht Moritz, seinen Standpunkt zu erklären. Er weiß aus eigener Erfahrung, dass motivierte Entwickler in der Lage sind, fachliche Themen sehr genau zu analysieren und ausgezeichnete Dokumentation zu schreiben. Sie tun das aus dem Wunsch heraus, das in der Story formulierte Problem ganz genau zu verstehen. Dann suche sie eine passende Lösung. Offene Punkte klären sie mit dem Product-Owner. Manchen Teams reicht verbale Kommunikation. Trotzdem gibt es häufig eine Person im Team, die ganz genau mitschreibt. Schnell entstehen dadurch eine persönliche Zusammenstellung von Wissen zur Story. Es gelingt dieser Person, alle wesentlichen Informationen an eine zentrale Stelle zu bringen. So ein in der Regel wenig strukturiertes Arbeitsdokument erlangt im Team schnell den Status der “Wahrheit”, zumindest für den Augenblick. Alles Wissen an einem Ort. Sehr praktisch.

Die Präsentationen heute im Weekly haben eindrucksvoll gezeigt, dass die Studenten sich sehr gut vorbereiten, weniger mit Text, mehr mit Tabellen und Diagrammen. In ihren tabellarischen Übersichten finden sich alle Varianten, die es nach ihrem Verständnis der Story gibt. Für alle wichtigen Informationsobjekte erstellen sie umfassende Klassendiagramme mit allen Attributen und Relationen und allen Details zu Typen und Constraints. Mit Sequenzdiagrammen skizzieren sie praktisch auf Methodenebene die geplanten Abläufe innerhalb der Komponenten.

All diese Tabellen und Bilder sind völlig in Ordnung, keine Frage. Aber sie sind viel zu detailliert für eine nachhaltige Produktdokumentation. Sie enthalten viele redundante Zusatzinformationen, die aus anderen Dokumenten abgeleitet sind, z.B. das konkrete Ergebnis einer angewendeten Regel aus einem Konzept. Ihre Klassen- und Sequenzdiagramme sind sehr genau. Sie sind code-nah. Um diese Art von Dokumentation aktuell zu halten, müssen die Bilder permanent mit dem Code synchronisiert werden. Das klappt sehr gut, wenn die Komponente “jung” ist. Sobald eine Komponente eine gewisse Reife erreicht hat, werden Änderungen im Code nicht mehr so zuverlässig parallel in der Dokumentation nachgezogen. Das ist Arbeit, die gerne “später” gemacht wird. Damit veraltet die Dokumentation. Sie “verdirbt” sprichwörtlich.

Keine Sorge, es geht hier nicht um Viren und Würmer, die elektronisch gespeicherte Daten kaputt machen. Es geht vielmehr um die Frage, was mit der Qualität von Dokumenten passiert, die wir in einer irgendwie gearteten Ablage für eine gewisse Zeit speichern und zu einem späteren Zeitpunkt wieder hervorholen.

Weiterlesen auf  cardsplus.info

Es ist völlig normal, dass Entwickler während der Realisierung von ihrem ersten Plan abweichen. Sie haben mit Sicherheit gute Gründe dafür. In dieser Situation wollen sie ganz einfach ihr Problem lösen. Sie denken nicht mehr an die Dokumentation. Eine Ursache ist die “Distanz” der Dokumentation zum Code. Entwickler nutzen sie als sekundäre Informationsquelle. Primär orientieren sie sich am vorhandenen Code, einer Spezifikation oder einer Konfigurationsdatei. Auch Testfälle sind für Entwickler ein ganz wichtige Informationsquelle. Das ist völlig normal, denn Entwicklung ist Transformation von Wissen in ausführbare Programme.

Ein Team braucht am Beginn eines Sprints sehr viel detailliertes Wissen, um ein Problem korrekt und vollständig zu verstehen. Nur so kann das Team eine angemessene Lösung finden. Dieses Wissen wird dann in Code transformiert. Aus den Akzeptanzkriterien werden Testfälle.

Weiterlesen auf cardsplus.info

Wissen aus der vorab erstellten Dokumentation steckt also im Code. Gab es bei der Transformation, also beim Programmieren, Abweichungen von der ursprünglich formulierten Idee, dann passen Code und Dokumentation nicht mehr zusammen. Das sind oft nur kleine Unterschiede. Aber die Dokumentation verliert Qualität, hat kleine Ungenauigkeiten oder Fehler..

Und schließlich das letzte Problem, das Moritz anspricht: « Macht euch bitte bewusst, dass Klassen- und Sequenzdiagramme nach Abschluss der Implementierung eigentlich nicht mehr gebraucht werden. Code ist immer die bessere, weil “exaktere” Antwort auf die Frage, wie eine Datenstruktur aufgebaut ist oder wie eine Methode funktioniert. Nur im Code steckt die Wahrheit! »

Zum Abschluss seines Vortrages appelliert Moritz an die Studenten: « Fragt euch bitte, ob ihr eine sehr detailreiche Beschreibung oder grafische Darstellung nach Abschluss der Implementierung wirklich braucht, damit ihr und andere Entwickler euren Code verstehen. »

Die Studenten scheinen das Problem zu verstehen. Sie erkennen das Dilemma:  Am Beginn einer Implementierung benötigen sie sehr viel Informationen mit wesentlich größerer Detailtiefe, als sie später für das Verstehen des fertigen Codes brauchen. Der Code ist ja lesbar. Testfälle zeigen, was der Code leistet.

Für dieses Dilemma hat Moritz zwei Lösungsvorschläge. Beide möchte er gleich im Anschluss mit den Studenten besprechen. Sie wollen sich dafür maximal eine Stunde Zeit nehmen, inklusive Diskussion und Entscheidung, wie sie zukünftig vorgehen wollen.

Zuletzt veröffentlichte Beiträge: