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


Gleich zu Beginn des Weekly überreicht Moritz ein Stofftier. Es soll ein greifbares Symbol für die Übernahme der gemeinsam genutzten cloud-basierten Testumgebung durch eine Arbeitsgruppe sein. Das Team konnte oder wollte sich auf kein bestimmtes Stofftier festlegen und überließ Moritz die Wahl. Sie fiel auf einen bunten Hasen, eine Spende von Moritz’ Tochter Sophie. Gut gelaunt investieren sie weitere fünf Minuten für eine Abstimmung über den Namen des Hasen. Schnuffel (Sophies Vorschlag), Bugs (nicht überraschend), Ossi (von Osterhase) und Hase (nicht sehr kreativ) stehen zur Wahl. Es wird einstimmig Ossi.

Im weiteren Verlauf des Weekly sinkt die Stimmung von Moritz. Das Team hat zwar Fortschritte bei der Stabilisierung der Software gemacht und wortreich erklärt, was sie alles geändert und verbessert haben. Aber es wird klar, dass sie in letzter Zeit das Wiki stark vernachlässigt haben.

« Wir haben die Architekturwand aktualisiert. », rechtfertigt sich Richard.

« Fein, finde ich gut. Die Architekturwand ist ja auch eine wichtige Arbeitsgrundlage für euch. », entgegnet Moritz. « Habt ihr die Änderungen auch im Wiki nachgezogen? »

Betretenes Schweigen.

« Ich dachte, wir waren uns einig, dass die Produktdokumentation ein wichtiger Teil eurer Arbeit ist. Mit CARDS+ seid ihr in der Lage, inkrementell zu dokumentieren, gleichzeitig mit der Entwicklung. Mir geht es vor allem um die Qualität. Ich möchte keine Nachdokumentation. Die ist lästig und häufig nur Alibi. »

Moritz schlechte Laune ist jetzt spürbar. Er weist darauf hin, dass die Studenten für eine positive Beurteilung eine Abschlussdokumentation mit aktualisiertem Pflichtenheft abgeben müssen. « Keine Dokumentation ist keine Option für euch. Vergesst das bitte nicht. »

Mit dem Versprechen des Teams, die fehlenden Anpassungen im Wiki gleich im Anschluss im Teamwork nachzuholen, schließen sie das Weekly für heute ab.

Während die Studenten sich an die Arbeit machen, hängt Moritz seinen Gedanken nach. Er reflektiert für sich selbst das Thema Arbeitsdokumente. Sie sind an und für sich eine gute Sache. Sie fassen verstreute Informationen an einer Stelle zusammen. Kompakt, gerade richtig aufbereitet für den Bedarf der Entwickler. Die Architekturwand ist so ein Beispiel, oder jede Story in Trello.

Leser, die keine Entwickler sind, tun sich oft schwer mit Arbeitsdokumenten, die von Entwicklern in der Regel für Entwickler geschrieben wurden. Eine Ursache ist “Spaghetti-Text”. Entgegen dem Prinzip KISS schreiben Entwickler ihre Sicht der Dinge gerne kontinuierlich und ohne erkennbare Struktur auf. Ein typisches Beispiel sind Listen von Code-Schnipseln oder Konfigurationen mit mehr oder weniger verständlichen Erklärungen. In allen Fällen aber gilt: Nur der Autor weiß, ob der Inhalt komplett ist.

Jeder Entwickler hat seine eigene persönliche Vorliebe für das Werkzeug zur Erstellung und Bearbeitung seiner Arbeitsdokumente. Mancher nutzt einfach Bleistift und Notizblock. Häufig ist es ein simpler Texteditor: Vi(m), Notepad, PSPad, Textpad, Ultraedit, um nur einige wenige zu nennen. Besonders in größeren Teams wird ein Wiki gerne angenommen. Es unterstützt die Kommunikation im Team. Alle Entwickler können gleichzeitig an Seiten arbeiten oder für andere sichtbar Kommentare abgeben. Confluence unterstützt das beispielsweise sehr gut. Kommentare sind wertvoll. Nicht moderierte Kommentare können aber sehr schnell zur Belastung werden.

Kommentare unterstützen die Kommunikation im Team. Sie machen Feedback einzelner Personen für alle sichtbar. Sie lösen eine Diskussion aus, wenn es kontroverse Kommentare gibt. Sie sind die einzig verfügbare messbare Größe für die Qualität einer Seite. Darum ist es besonders wichtig, dass Autoren Kommentare moderieren, d.h. aktiv bearbeiten und danach löschen. Nur eine Seite ohne Kommentare ist eine gute Seite.

Weiterlesen auf cardsplus.info

Egal wie mächtig ein Werkzeug ist und wie viele Funktionen es hat: Den Inhalt bestimmt der Autor. Qualität ist das Ergebnis kontinuierlicher Verbesserung, an der sowohl Autoren als auch Leser ihren Beitrag leisten müssen. Bei Arbeitsdokumenten kennt nur der Autor die Struktur und das Ziel “seines” Dokumentes. Für andere, an der Erstellung des Arbeitsdokumentes nicht beteiligte Leser, ist es schwer bis unmöglich, den Inhalt auf Korrektheit und Vollständigkeit zu prüfen. Eine gemeinsames Bearbeiten gestaltet sich schwierig.

Moritz’ wird jäh aus seinen Gedanken gerissen, als Anne, Richard und Georg bei ihm vorbeischauen. Sie sind unsicher, wie sie ihre ganzen zwischenzeitlich entstandenen Arbeitsdokumente in das Wiki übernehmen können. Schnell wird Moritz klar, dass er ihnen beim Sichten und Sortieren helfen muss. « Nicht jedes Arbeitsdokument müsst ihr in die Produktdokumentation übernehmen. Fragt euch immer, ob ihr ein Dokument, eine Liste oder ein Bild dauerhaft braucht. »

« Jetzt bin ich verwirrt. Die ganze Zeit über erzählst du uns, wie wichtig Bilder sind. Von Anfang an hast du uns gesagt, wie wichtig die Darstellung der Systemstruktur in einem Bild ist. Wir haben das natürlich ernst genommen und selber Bilder für uns gemacht. Und plötzlich brauchen wir sie nicht mehr. Das verstehe ich nicht. », sagt Anne.

« Bilder sind wichtig, keine Frage. Der Komponentenüberblick steigert den Wert der Systemstruktur. Er zeigt die Komponenten in ihrem Kontext. Auf einen Blick können wir Abhängigkeiten erkennen. Das ist hilfreich. Oder ein Klassendiagramm. Es zeigt sehr gut Zusammenhänge zwischen Daten. », antwortet Moritz. « Bilder dürfen nicht zu kompliziert sein. Gute Bilder sind selbsterklärend. Wenn ich aber ein Bild nur dann verstehe, wenn ich vorher eine halbe Seite Erläuterung gelesen habe, dann kann ich möglicherweise auf das Bild verzichten. Der erläuternde Text könnte schon reichen. »

Gemeinsam gehen sie alle ihre Abbildungen und Diagramme durch. Sie stellen fest, dass manche Bilder schon jetzt in kleinen Details falsch sind. Eine Ursache ist sicher die große Menge an Details. Eine mögliche Lösung ist das Vereinfachen der Bilder. Moritz bietet seine Mithilfe bei dieser Transformation an. Am Ende sind sie sich einig, dass die vereinfachten Bilder verzichtbar sind. Sie übernehmen nur die Skizzen der Screens in das Wiki zu.

Danach sichten sie ihre Mitschriften und Listen. Moritz erkennt sehr viel wertvolles Wissen. Es fehlt aber Struktur. Manche Texte sind außerdem etwas holprig. Moritz schlägt eine schrittweise Übernahme in das Wiki vor. « Übernehmt ihr ein Arbeitsdokument in die Produktdokumentation, dann nutzt die Chance und überprüft und verbessert den Inhalt. Korrigiert Schreibfehler, vermeidet Wiederholungen durch Verlinkung mit dem Glossar – Prinzip DRY. Strafft die Texte und entfernt zu detailreiches Geblubber – Prinzip KISS. Teilt die Inhalte der Arbeitsdokumente gemäß den Bausteinen von CARDS+ auf – Prinzip SRP. »

Moritz erzählt von einer bewährten Praxis bei der teilweisen Übernahme von Texten aus Arbeitsdokumenten. « Übernehmt ihr eine Passage aus einem Arbeitsdokument, dann löscht den Text nicht, sondern lasst ihn stehen, aber ändert das Format auf Durchgestrichen. Direkt darunter fügt ihr einen Link auf jene Seite ein, in der jetzt die Information steht. Der Link ist hilfreich und gleichzeitig eine Begründung für den gestrichenen Text. »

In einem Kraftakt bringen sie mit dieser Strategie das Wiki auf Vordermann. Damit diese Situation zukünftig nicht mehr eintritt, wollen sie bei diesem dreistufigen Arbeitsprozess bleiben.

Die erste Stufe beginnt mit dem Start der Entwicklung einer neuen Komponente. Jetzt nutzen sie ganz bewusst Arbeitsdokumente, ohne Vorgaben für Form und Struktur. Wiederholungen, detaillierte Bilder, alles ist erlaubt. Hauptsache, es hilft bei der Programmierung.

Nach dem vorläufigen Abschluss der Entwicklung einer Komponente beginnt Stufe Zwei. Gleichzeitig mit der Realisierung abschließender Testfälle löst das Team die Arbeitsdokumente langsam wieder auf. Eine Komponente ist fertig, wenn ausreichend Testfälle zeigen, dass der Code wie erwartet funktioniert und die Produktdokumentation im Wiki aktuell ist.

Hat eine Komponente die Reife für den produktiven Einsatz erreicht, beginnt Stufe Drei. Arbeitsdokumente sind nun nicht mehr erwünscht. Alles aufbewahrenswerte Wissen, das zu diesem Zeitpunkt noch frisch in den Köpfen der Entwickler verankert ist, wird in das Wiki übernommen. Nach einer letzten Prüfung werden die Arbeitsdokumente “entsorgt”.

Spätere Änderungen an produktiven Komponenten werden nach Abschluss der dritten Stufe ohne Umweg über Arbeitsdokumente direkt in den Bausteinen der Produktdokumentation erfasst. Die Komponente ist in dieser Phase eine Einheit bestehend aus Code, Testfällen und Seiten im Wiki. Jede Änderung wirkt sich in der Regel auf alle drei Bestandteile aus.

Moritz hat seine schlechte Laune längst überwunden. Er ist überzeugt, einen Weg gefunden zu haben, wie sie Qualität in die Dokumentation bringen, ohne faulen Kompromiss. Angemessen im Umfang. Nachhaltig in der Wirksamkeit.

Zuletzt veröffentlichte Beiträge: