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


Bei der ersten Lösung betrachten sie die Tabellen und Diagramme, die sie im Teambereich erstellt haben. Moritz bezeichnet sie als Arbeitsdokumente. Sie sind Teil der Projektdokumentation und werden nur so lange gepflegt, wie sie vom Team gebraucht werden. Aber wie lange ist das?

In einer Microservice-Architektur ist es möglich, eine Komponente als fertig zu bezeichnen, obwohl das Produkt noch nicht fertig ist. Das ist dann der Zeitpunkt, die Arbeitsdokumente aufzulösen, die für die Fertigung dieser Komponente angelegt wurden. Natürlich wollen sie wichtiges Wissen erhalten und in die Produktdokumentation übernehmen. Aber wie?

In seiner Rolle als Gärtner in einem Projekt – einem sehr großen Projekt mit fünf Teams – hat Moritz für sich ein Vorgehen entwickelt, mit dem er das Wissen aus Arbeitsdokumenten der Teams in das Wiki übernimmt.

Moritz beschreibt sein Vorgehen: « Ich bin bei jedem Review dabei. Dort erfahre ich aus erster Hand, was die Teams im vergangenen Sprint geleistet haben. Das ist für mich ein erster Hinweis, welche Teile der Produktdokumentation ich kontrollieren bzw. aktualisieren muss. »

Moritz zeigt die Produktdokumentation seines aktuellen Projektes. Am Beispiel einer Service-Seite, die er zuletzt geändert hat, erklärt er sein weiteres Vorgehen: « Ein an der Umsetzung der Komponente beteiligter Entwickler erklärt mir, wie die Komponente funktioniert. Er zeigt mir natürlich alle Arbeitsdokumente und Testfälle. Ich kann mir auch Code ansehen, wenn sie für mein Verständnis nützlich sind. »

Im nächsten Schritt nutzt Moritz sein neu erworbenes Wissen über die Implementierung, um die nach seiner Einschätzung wichtigen Informationen aus den Arbeitsdokumente in die Produktdokumentation zu übernehmen. Die Information aus den Arbeitsdokumenten teilt er gemäß den Bausteinen von CARDS+ auf. So kann er viele Texte kürzen, sozusagen auf den Punkt bringt. « Natürlich versuche ich, die Texte unter Verwendung des Glossars noch kompakter zu machen. »

Ausgangspunkt für die Implementierung ist eine Story mit einem Standardfall für eine Funktion des Produktes. Durch Probleme in den Prozessen der Organisation, die das Produkt nutzt, ergeben sich fachliche Sonderfälle mit einer Lösung, die vom Standardfall maßgeblich abweicht. Die gleiche Situation entsteht bei «unsauberen» Daten an technischen Schnittstellen. Eine abweichende Lösung erkennt man leicht daran, dass in den Essenzschritten der Lösung vermehrt Formulierung wie «wenn … dann .. sonst» vorkommen oder Bedingungen für Essenzschritte gelten.

Jeder dieser Sonderfälle wird mit dem Baustein Case erfasst. Ziel ist es, die Abweichung, das Besondere des Sonderfalles sichtbar zu machen.

Weiterlesen auf cardsplus.info

Für die Programmierung von Komponenten wird nicht nur individueller Code geschrieben. Es gibt Abhängigkeiten zum Code von Open-Source- oder kommerziellen Produkten. Diese Abhängigkeit kann im Steckbrief von Baustein Service als Liste von Modulen erfasst (vgl. Baustein Spec).

Wichtige Geschäftsregeln, die häufig erst bei der Umsetzung nach Rücksprache mit dem Product-Owner formuliert werden, gehören in die Service-Seite jener Komponente, in der sie tatsächlich implementiert wurden. Dort werden sie am ehesten von Entwickler erwartet und auch gepflegt.

Weiterlesen auf cardsplus.info

Nicht funktionale Aspekte gelten in der Regel für mehr als eine Komponente. Dieses gemeinsame Verhalten wird als technisches Konzept mit dem Baustein Spec festgehalten. Es ist das Versprechen der Entwickler, für gleichartige Probleme nur eine einzige Lösung zu verwenden. Diese Einschränkung hilft dabei, dass andere Entwickler den Code schneller verstehen. Der größte Gewinn entsteht jedoch durch ein einheitliches Vorgehen beim Test, bei der Installation und beim Betrieb einer Komponente. Gemeinsame Lösungen sind daher in der Regel Forderungen der Tester und DevOps.

Bei der Implementierung einer Komponente wird nicht nur individueller Code geschrieben. Es gibt Abhängigkeiten zum Code von Open-Source- oder kommerziellen Produkten. Als Modul hilft der Baustein Spec bei der Beschreibung von Bibliotheken, Infrastruktur oder Datenbanken. In diesem Zusammenhang sind die Lizenz, bekannte Einschränkungen und Probleme und die Möglichkeit eines professionelles Support besonders interessant.

Weiterlesen auf cardsplus.info

Bei der Realisierung der internen Datenverarbeitung einer Komponente spielen Datenstrukturen eine wichtige Rolle. Solche Datenstrukturen können mit dem Baustein Entity beschrieben werden. Es geht dabei nicht um die technischen Umsetzung, also keine Beschreibung einer Datenbanktabelle mit ER-Diagramm, Spalten- und Index-Definitionen oder ein Schema mit Typen und Constraints für generierte Klassen. Ziel ist es, nur ausgewählte Informationsobjekte zu erfassen und wichtige Attribute und Relationen für das Verständnis der Zusammenhänge zu beschreiben, ohne zu sehr ins Detail zu gehen.

Weiterlesen auf cardsplus.info

Mindestens ein Entwickler, im Idealfall alle an der Implementierung beteiligten Entwickler lesen die geänderten Seiten im Wiki Korrektur. Sie prüfen, ob auch aus ihrer Sicht noch alle wichtigen Informationen vorhanden und verständlich sind – klarerweise aus ihrer Perspektive. Dieses Vorgehen ist an dem Prinzip “reverse presentation” angelehnt, das Moritz in einem seiner größeren Projekte mit Offshore-Entwicklung in Indien kennengelernt hat.

« Willst du damit sagen, dass du jedes Arbeitsdokument mit dem Abschluss einer Implementierung durchforsten wirst, um die “Rosinen” herauszupicken? », fragt Tim. « Und wir dürfen danach das Ganze noch einmal lesen, wenn du fertig bist? »

« Ja, das meine ich. », antwortet Moritz leicht amüsiert. Immerhin gilt Tim im Team als schreibfaul, zumindest was das Schreiben von Dokumentation angeht.

Aber Moritz nutzt die Frage von Tim als Gelegenheit, um seinen Standpunkt darzustellen. « Als Entwickler sind euch sicher die Grundsätze der Clean-Coder bekannt. Die Pfadfinderregel zum Beispiel. Durchführung von Reviews. Oder das KISS-Prinzip. »

Sie nicken. Moritz weiß von Julius, Richard und Anne, dass sie Verfechter sauberen Codes sind. Er fordert sie auf, diese Grundsätze der sauberen Programmierung auf das Schreiben von Dokumentation zu übertragen.

« Beginnen wir mit der Pfadfinderregel. Dokumentation muss gelesen, aktiv genutzt werden. Nur Leser finden Fehler. », erklärt Moritz. Er hat folgenden fatalen Ausblick für die Studenten: « Verliere ich euch als Leser und aktive Nutzer der Produktdokumentation, verliere ich euer Feedback. Ohne Feedback sinkt die Qualität. Immer mehr Texte und Abbildungen stimmen nicht mehr mit der Realität überein. Diese Fehler führen dann zu Misstrauen bei euch. Ihr verlasst euch noch mehr auf eure eigenen Arbeitsdokumente. Für mich als PO ist das ein fataler Teufelskreis! »

Auch für das KISS-Prinzip hat Moritz eine Analogie. « Stellt euch einen Text vor mit besonders langen, geschachtelten Sätzen. Ihr lest ihn zum dritten Mal. Trotzdem seid ihr nicht sicher, was der Autor euch sagen will. »

« Ich lass’ mir den Text vom Autor erklären. Ich halte eh direkte Kommunikation für besser. », antwortet Tim.

« Klar. Verstehe ich. Und vermutlich wirst du den Text kein weiteres Mal lesen. Richtig? », folgert Moritz aus Tims Antwort. « Dann befinden wir uns schon wieder im zuvor schon beschriebenen Teufelskreis. »

Zuletzt geht Moritz noch auf das DRY-Prinzip ein. Wie bei dupliziertem Code können sich kopierte Texte widersprechen, wenn verschiedene Personen gemeinsam an einer Dokumentation arbeiten. Was nach Moritz’ Meinung total normal ist. Das Glossar ist ein ganz wichtiges Mittel, um diesem Problem zu begegnen.

Moritz hat ein weiteres Beispiel für die Anwendung von DRY und ein sehr gutes Argument für die Medienbibliothek: « Die Verwendung von Bildern kann in einem Wiki schnell zum Problem werden. Leider bietet Confluence die Möglichkeit, Bilder als Anhang in jeder beliebigen Seite einzufügen, ganz einfach mit Drag-And-Drop. Damit gibt es ganz schnell mehr als eine Kopie eines Bildes. Wird ein Bild in einer Seite aktualisiert, steht sie im Widerspruch zu einer älteren Version des Bildes in einer anderen Seite. Die Dokumentation wird inkonsistent. »

Das DRY-Prinzip hilft nicht nur durch Reduzierung der Texte, sondern kann auch zur Vermeidung von Texten führen. « Nehmen wir als Beispiel ein Arbeitsdokument mit der Beschreibung eines REST-API, mit allen Operationen, Attributen, Typen und Constraints. Nehmen wir weiter an, dass mit dem Abschluss der Umsetzung eine vollständige Spezifikation mit Swagger existiert. Brauchen wir dann noch eine Dokumentation des REST-API im Wiki? »

« Code oder eine code-nahe Spezifikation ist in diesem Fall sicher besser. Auf jeden Fall aktueller. », bestätigt Julius.

Moritz erklärt den Studenten, dass sich noch viele weitere Grundsätze der Clean-Coder auf das Dokumentieren übertragen lässt. Aufgrund der fortgeschrittenen Zeit verweist er sie diesmal auf die Methode CARDS+.

Dokumentieren ist ein Handwerk. Wir können unsere Kreativität effizient “zu Papier” bringen, wenn wir die notwendigen Fähigkeiten besitzen. Prinzipien der Methode CARDS+ helfen uns dabei. Viele Prinzipien der Programmierer gelten auch für Autoren, in den meisten Fällen in nur leicht abgewandelter Form.

Weiterlesen auf cardsplus.info

Zuletzt veröffentlichte Beiträge: