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


Eine Abbildung von Richard, für die er sich offensichtlich ganz besonders viel Mühe gemacht hat, ist Moritz’ Aufhänger für die zweite Lösung als Ausweg aus dem Dilemma der Arbeitsdokumente. Die Architekturtapete – so Richards Name für dieses Bild – ist ein ganz aktuelles, mit sehr vielen Angaben zu Technologien und Hinweisen zu den konkreten Datenflüssen gespicktes Bild. Es steckt geballtes Wissen über den aktuellen Stand der Entwicklung im Backend in diesem Bild. Richard deutet an, dass er die Absicht hat, noch mehr Informationen in das Bild zu packen.

Diese Abbildung muss nach Moritz’ persönlicher Einschätzung in jedem Produktinkrement umfangreich angepasst werden. « Gegenüber dem Zielbild fehlen unter anderem die Fahrplanlogik und die Nutzerverwaltung komplett. Außerdem kommen eine ganze Reihe Datenquellen für Objekte, Dienste und Termine dazu. », begründet er seine Einschätzung. Der Überblick wird allein durch Weiterentwicklung fehlerhaft oder mindestens teilweise unvollständig.

Jetzt passiert, was Moritz befürchtet hat. Richard beginnt sich zu verteidigen: « Ich dachte, ich hätte deine Methode CARDS+ verstanden. Wir haben gemeinsam den Überblick entworfen. In den letzten Wochen haben wir uns intensiv damit beschäftigt, diese Komponenten zu realisieren. Ich wollte diese Ergebnisse für uns sichern. »

« Ich habe schon mehrfach gesagt, dass nichts gegen Arbeitsdokumente spricht. », versichert Moritz. « Wenn dir dieses Bild bei deinen Aufgaben hilft, dann hat es auch einen Wert für dich. Aber es gehört nicht in die Produktdoku. »

Richards Enttäuschung ist spürbar: « Warum nicht. »

Moritz versucht Richard schonend seinen Standpunkt zu erklären: « Weil du es allein pflegst. Du bekommst keine Stabilität in das Bild. Dafür sind zu viele Details enthalten. Nach meiner Erfahrung wirst du bald die Lust verlieren, das Bild in jedem Sprint anzupassen. »

Moritz erinnert die Studenten, dass er ihnen einen Ausweg anbieten kann. Er erzählt von einem Projekt mit mehreren Teams. Sie wollten den aktuellen Stand ihres Software-Produktes darstellen. Ihre Lösung war die Architekturwand. An einer großen freien Wand hingen beschriftete Klebezettel für jede Komponente. Klebestreifen zwischen den Komponenten stellten Datenflüsse dar. Vertreter aller Teams trafen sich für einen Austausch regelmäßig vor dieser Wand. Gemeinsam korrigierten sie Fehler oder fügten neue Elemente hinzu. Das Projekt wurde nach und nach verkleinert, bis nur mehr ein Team für die Wartung übrig war. Bald danach hatte auch die Wand ausgedient und wurde entfernt.

Moritz blickt in die Runde und fragt: « Was denkt ihr? »

« Die Idee finde ich total spannend!”, antwortet Richard. “Ich hab mal einen Artikel gelesen über Dokumentation von Software-Architekturen. Der Autor meinte, dass so eine Wand der agile Weg wäre. Beim Lesen war ich aber nicht wirklich überzeugt, muss ich sagen. »

Julius und Georg kennen eine vergleichbare Idee mit ausgedruckten Bildern an einer Pinnwand, zusammen mit dem analogen Sprint-Backlog mit handgeschriebenen Aufgaben. Auf dem Ausdruck wurden beim Daily immer wieder Hinweise geschrieben, ungültige Elemente durchgestrichen oder neue Verbindungen eingezeichnet, bis das Bild nicht mehr brauchbar war. Dann wurde das Bild neu ausgedruckt. Die Hinweise waren verloren. Oft fehlten Elemente im Bild, weil die Druckvorlage nicht ausgebessert wurde. « Das war nicht optimal. », meinen beide übereinstimmend.

Anne ergänzt: « Platz genug haben wir ja. Kannst du sicherstellen, dass niemand außer uns die Wand verändert? »

« Ja, kann ich. », bestätigt Moritz.

Tim hat erste Bedenken: « Wir treffen uns nur am Dienstag hier bei der Wand. Was mache ich an den anderen Tagen? »

« Ich würde vorschlagen, dass wir am Dienstag dafür sorgen, dass die Wand in Ordnung ist. Am Ende des Tages machen wir ein Foto. Das speichern wir im Teambereich ab, jede Woche eine neue Version. Dann kannst du immer und jederzeit die Wand betrachten. Wäre das in Ordnung für dich? », fragt Moritz.

Tim ist nicht überzeugt. Die Diskussion im Team geht noch eine ganze Weile weiter. Am Ende stellen sie fest, dass sie auf jeden Fall noch überlegen müssen, ob die Architekturwand für sie passt.

Moritz hat noch einen weiteren Vorschlag: « Es gibt Werkzeuge, mit denen sich aus einfachen Textdateien UML-Diagramme erstellen lassen. Die Texte werden zusammen mit dem Code in das Git-Repository eingecheckt. »

yUML ist ein Online-Service, welches mit einer speziellen Auszeichnungssprache das Erstellen von Klassen- und Use-Case-Diagrammen ermöglicht.

Weiterlesen auf https://yuml.me/

Für Visual Studio gibt es eine Integration von yUML.

PlantUML ist ein Werkzeug, welches mit einer speziellen Auszeichnungssprache das Erstellen von Diagrammen ermöglicht. Dazu zählen u.a. die aus der UML bekannten Klassen- und Sequenzdiagramme und Gantt-Diagramme. Auch das Zeichnen von Wireframes ist möglich.

Weiterlesen auf http://plantuml.com/

Für IntelliJ IDEA gibt es eine Integration von PlantUML.

Für Visual Studio gibt es eine Integration von PlantUML.

Auch hier kann Moritz aus der Praxis erzählen. Entwickler in einem Projekt bei einer Bank nutzen Asciidoc, um Handlungsanweisungen für den Betrieb einer Komponente zu schreiben. Es ist klar, dass ein Entwickler am besten beschreiben kann, wie ein Komponente von außen beeinflusst werden kann und wie sie sich verhält. Mit Asciidoc schreibt der Entwickler Text wie Code. Er muss nicht das Werkzeug wechseln, um zu dokumentieren. Und selbst Diagramme kann er durch den Einsatz von PlantUML erstellen. Dieser “Code” der Auszeichnungssprache von Asciidoc und PlantUmL wird als lesbares Dokument in seinem Editor angezeigt. Beim Ausliefern der Komponente wird ein passendes Format, hier PDF, erzeugt und zu einer Gesamtdokumentation zusammengeführt. Ein handgeschriebenes Hauptdokument bildet den Rahmen, ein automatisch erstelltes Inhaltsverzeichnis hilft bei der Navigation.

Moritz endet mit den Worten: « Markdown ist eine wunderbare Möglichkeit, Dokumentation näher zum Entwickler zu bringen. Ohne Medienbruch, alles ist Code, alles ist im Git. Es ist die Chance, sehr code-nah eine Dokumentation bereitzustellen, die höchste Qualität hat. Oder zumindest haben kann. »

AsciiDoc ist Werkzeug für eine textbasierte Dokumentengenerierung. Grundlage ist eine leichtgewichtige Auszeichnungssprache. Ähnliche Sprachen kennt man von Github (Markdown) oder Wikipedia (Wikitext). Die Textdateien können wie Quellcode in einem Git-Repository eingecheckt werden.

Weiterlesen auf http://asciidoc.org/

Asciidoctor ist eine alternative Implementierung von Asciidoc. In der Auszeichnungssprache unterscheiden sich die beiden Werkzeuge. Anders als Asciidoc kann Asciidoctor sofort die Formate HTML5, EPUB3 und PDF ohne den Umweg über DocBook erzeugen.

Weiterlesen auf http://asciidoctor.org/

Für IntelliJ IDEA gibt es eine Integration von AsciiDoc.

Für Visual Studio gibt es eine Integration von AsciiDoc.

Tim ist begeistert: « So mag ich Dokumentation schreiben. Ich bin dabei! »

Moritz freut sich über Tims Begeisterung. « Das freut mich! », sagt er. « Vergiss bitte nicht, dass es trotzdem Regeln gibt. Auch diese Dokumentation muss prüfbar sein, muss für alle lesbar sein! »

Gleich ist ein Teil der Begeisterung bei Tim verschwunden.

« Du musst es positiv sehen. Dokumentieren ist wie Programmieren. In beiden Welten gibt es Spielregeln. Anders geht es nicht in einem Team. », rechtfertigt Moritz seinen Einwand.

« Ich denke, wir sollten vor allem die Vorteile sehen. », sagt Anne. « Die Doku ist dort, wo auch Code und Unit-Tests sind. Alles zusammen. »

Julius ergänzt: « Doku praktisch wie Code zu schreiben ist total interessant. Ich schreibe ein Stück Code, erstelle einen Testfall oder aktualisiere die Doku. Immer im gleichen Editor. Irgendwie cool. »

« Das läuft doch gut. », denkt Moritz. Er macht den Vorschlag, bis nächste Woche zu überlegen, wie eine Produktdokumentation aussieht, die sowohl aus Markdown-Dokumenten im Git als auch Wiki-Seiten in Confluence besteht. Sein Ziel ist es, dass sich die beiden Dokumentationsarten ergänzen. Die Methode CARDS+ macht ihm dabei große Hoffnung.

Eines der wohl wichtigsten Ziele der Methode CARDS+ ist die weitestgehend redundanzfreie Ablage von Inhalten über alle Dokumentationsarten hinweg. Eine Änderung an einer Stelle kann immer dazu führen, dass eine Information an einer anderen Stelle widersprüchlich dazu ist. Die Gefahr wird durch konsequente Verlinkung der Dokumente reduziert. Autoren erkennen dadurch Abhängigkeiten und können die Widersprüche sofort auflôsen.

Weiterlesen auf cardsplus.info

Nachhaltigkeit im Zusammenhang mit einer Produktdokumentation steht für das Bestreben, Wissen über ein Produkt permanent zu sammeln und für alle Zielgruppen verfügbar zu machen. Es geht um das Versprechen, jede Änderung am Produkt bekannt zu machen, zu veröffentlichen. Nachhaltig dokumentieren bedeutet sofort zu dokumentieren, also die Aufgabe nicht auf später zu verschieben.

Weiterlesen auf cardsplus.info

Redundanzfreie Inhalte sind nur dann möglich, wenn lesbare Artefakte der Entwickler, also Testfälle, Spezifikationen, API-Dokumentationen, Skripte oder Konfigurationsdateien, Teil der Produktdokumentation sind. Eine Komponentenbeschreibung mit Handlungsanweisungen in Asciidoc betrachtet Moritz als sehr sinnvolle Ergänzung. Er stellt sich jedoch die Frage, wie er den Überblick behalten kann in diesem wachsenden Zoo von Artefakten. Und er muss sich Gedanken machen über ein Versionierungskonzept für Dokumentation in Git und Confluence.

Zuletzt veröffentlichte Beiträge: