Alljährlich im Oktober finden in Essen die internationalen Spieltage, kurz “Spiel” genannt, statt. Auf der weltweit größten Publikumsmesse für Gesellschaftsspiele können Besucher aktuelle Neuerscheinungen auf dem Brettspielmarkt ausprobieren. Letzte Woche war es wieder so weit. Wie  die letzten Jahre auch waren ich mit meiner Frau 2 Tage vor Ort (Donnerstag und Freitag) und wir hatten Riesenspaß.

Kingdom Builder (Queen Games)

Besucher der Spiel werden viel mit Spielanleitungen konfrontiert. Ist Ihnen schon einmal aufgefallen, dass diese immer den gleichen Aufbau haben?

1. Kurze atmosphärische Einführung (optional, entfällt bei abstrakten Spielen)
2. Ziel des Spieles
3. Spielmaterial
4. Spielvorbereitung (Aufbau)
5. Spielablauf (Phasen, Züge, Aktionen)
6. Spielende (End- und Siegbedingungen)
7. Varianten (optional, z.B. für abweichende Spielerzahl, Expertenversion, Solospiel)

Die viel spielenden Messebesucher wären sehr überrascht, wenn eine Anleitung auf feste Bestandteile verzichten würde, oder die Spielvorbereitung mitten drin erklärt würde.

Auch wenn man das Spiel zwar kennt, aber länger nicht mehr gespielt hat, kommt die Anleitung zum Einsatz. Typische Fragen:

• Wie viele X bekommt jeder am Anfang? (X = Karten, Ressourcen, Pöppel, …)
• Wann genau ist das Spiel zu Ende?
• Geben X, die man am Ende über hat, Punkte?

Man darf erwarten, solche Fragen durch die Spielanleitung beantwortet zu bekommen, ohne sie von vorne bis hinten durchlesen zu müssen. Auch dabei hilft die Struktur.

Spielregeln Kingdom Builder

Von Spielanleitungen zu Architekturbeschreibungen

Genau wie bei Spielanleitungen verspricht eine vorgegebene Struktur auch für Architekturbeschreibungen Vorteile. Eine feste Gliederung der Inhalte unterstützt Autoren und Leser gleichermaßen. Als eine frei verfügbare  und betont praxistaugliche Strukturvorlage zur Beschreibung von Softwarearchitektur ist arc42 von Peter Hruschka und Gernot Starke eine naheliegende Wahl. Das Template erfreut sich mittlerweile im Feld großer Akzeptanz und Bekanntheit.

Missverständnisse

Ein von mir sehr oft gehörtes Missverständnis: “Bei arc42 muss man dieses Word-Template ausfüllen.” Die Vorlage ist vorrangig als Struktur zur Verwaltung zu verstehen, wo jedes Arbeitsergebnis, das im Rahmen des Architekturprozesses anfällt, seinen Platz findet. Hier fällt der meist im englischen belassene Begriff Repository; er hat mit “Fundgrube” und “Verwahrungsort” recht aussagekräftige deutsche Entsprechungen. Aus dem Repository lassen sich dann zielgruppengerecht verschiedene Dokumente ableiten. Wie flexibel und mit wie viel Aufwand Sie solche Dokumente aus Ihrer Fundgrube ableiten können, hängt stark von der Wahl der Werkzeuge und Notationen ab. Ein einzelnes Word-Dokument mit dreistelliger Seitenzahl macht Sie unbeweglich.

arc42-Repo in einem Wiki

arc42 ist nicht alternativlos. In der Regel spricht aber wenig gegen die Verwendung. Am ehesten vielleicht organisatorische Randbedingungen, die explizit etwas anderes fordern. Bevor Sie aber mit einem weißen Blatt anfangen, sollten Sie arc42 zumindest als Inspiration und Ausgangspunkt für Ihre eigene Dokumentationsstruktur nehmen.

Da sitzen sie im Stuhlkreis, die 14 Diagrammarten der UML im Workshop “Mehr Empathie in der Modellierung”. Und da bricht es aus ihm heraus: “Keiner hat mich lieb. Ich will gesehen werden.” Kann einem schon Leid tun, das Deployment Diagramm.

Gerade bastle ich bei meinem Buch über Architekturdokumentation am Unterkapitel zur Verteilungssicht. Ich habe 4 UML-Bücher auf dem Schreibtisch, und in wirklich jedem werden Deployment Diagramme absolut stiefmütterlich behandelt (auch in denen von meinen Kollegen übrigens). Sie wissen nicht, was ein Deployment Diagramm (deutsch Verteilungs- oder Einsatzdiagramm) ist? Genau das meine ich!

Sieht ungefähr so aus:

In einem der 4 Bücher vermutete ich einen Fehler. Um es nachzuprüfen habe ich in die Spezifikation geguckt, und siehe da: gleiches Bild. Viel Raum nimmt es auch dort nicht ein. Zwingende Beispiele Fehlanzeige. Armes Teil.

Liegt wohl daran, dass UML doch eher für die Entwickler gedacht war. Früher haben Entwickler ja an den Betrieb immer als letztes gedacht (“OK läuft, und wie kriegen wir das jetzt in Produktion? Wer ruft an? Wir losen!”). Trends wie Cloud Computing und DevOps überwinden alte Vorbehalte und versöhnen die Lager ein wenig.

Was mach ich denn jetzt mit dem verheulten Deployment Diagram? Soll ich es in meinem Buch mal anders machen? Dem Diagramm Raum geben und zeigen, was es tolles kann? Zum Beispiel: Zeigen, wie aus abstrakten Bausteinen Dinge werden, die man verteilen kann. Beschreiben, wie mögliche Zielumgebungen aussehen. Und wie man die Dinge tatsächlich dort zum Laufen bringt.

Haben Sie ein Herz fürs Deployment Diagram? Setzen Sie es ein? Ich freue mich auf Ihre Kommentare! Oder geben Sie diesem Beitrag +1. Dann freut es sich.

Im unserem Stuhlkreis hat das Timing Diagram in der Zwischenzeit all seinen Mut zusammen  genommen …

Der Ausspruch “Ein Bild sagt mehr als tausend Worte” wird allgemein akzeptiert. Nicht immer transportiert ein Bild aber tatsächlich mehr Informationen als Text, oder kommuniziert sie effizienter. Nehmen Sie als Beispiel folgenden Satz:

Das System XY besteht aus den drei Subsystemen A, B, und C.

Alternativ könnte man diesen Sachverhalt auch als Aufzählungsliste darstellen.

Subsysteme von System XY:

• A
• B
• C

Das versteht jeder im XY-Projekt involvierte, vorausgesetzt er kann Deutsch und weiß, was ein Subsystem ist. Vergleichen Sie diese textuellen Darstellungen mit dem folgenden Bild, vielleicht eingebettet als Graphik in einem Wiki, dass Sie zur Dokumentation Ihrer Architektur nutzen.

System XY besteht aus den drei dargestellten Subsystemen

Auf den ersten Blick ist die Abbildung hübsch anzuschauen und beinhaltet die gleichen Informationen wie der Satz oben. Für das Bild muss man die Notation verstehen, sie ist hier noch recht intuitiv. Wer die UML nur ein wenig kennt weiß wie viel Deutungsspielraum in dem Diagramm liegt. So könnte es beispielsweise noch weitaus mehr Subsysteme von XY im Modell geben, das Diagramm zeigt halt nur drei davon. Um das Abzusichern könnte man das Diagramm mit einem beschreibenden Text versehen, etwa wie in der Bildunterschrift bereits geschehen.

Das Diagramm liefert nun gegenüber dem ursprünglich zitierten Satz kaum einen Mehrwert.

Dieses Beispiel soll Sie keineswegs davon abhalten, ihre Architektur zu visualisieren. Es gibt aber durchaus Fälle, wo sie stattdessen eine textuelle Beschreibung zumindest in Erwägung ziehen sollten. So kann ein Ablauf unter Umständen auch in Pseudocode notiert werden, anstatt ein Sequenzdiagramm anzufertigen.

Graphische Darstellungen spielen ihre Stärken in Situationen aus, die über das bloße Aufzählen weniger Elemente wie oben herausgehen:

• Hierarchische Strukturen, Verfeinerungen
• Abläufe, insbesondere Alternativen, Wiederholungen, Parallelität
• Beziehungen zwischen Strukturelementen (z.B. auch Spezialisierung, Verwendung)
• Kategorisierung von Elementen, z.B. durch unterschiedliche Symbole
• Auszeichnen von Elementen und Anreichern mit Informationen
• Anordnen von Elementen in Gruppen, Schichten, …

Im speziellen Fall hier läge der Vorteil von UML weniger im oben gezeigten Diagramm, als in der Tatsache, dass es weitere Diagramme gibt, welche die selben Elemente z.B. in Interaktion oder im Einsatz zeigen. Das einheitliche Modell sorgt dann für Konsistenz, wenn z.B. etwas umbenannt wird.

Zum Abschluss noch eine kleine Aufgabe für Sie zur Anregung! Betrachten Sie die folgende Visualisierung von Klaviermusik (aka Noten, hier konkret aus Schwanensee). Finden Sie Elemente, die oben als Stärken für eine graphische Darstellung genannt sind, in Noten wieder?

Visualisierung von Musik

Für den Fall, dass Sie keine Noten lesen können, hier ein paar Beispiele: die Parallelität der Hände (oben rechte Hand, unten linke), die Strukturierung in Takte, Anreichern mit Informationen (mf = Dynamik mezzoforte, Ziffern = beim Spiel zu verwendende Finger). Tatsächlich lassen sich sämtliche Punkte von oben aufzeigen.

Ich platze vor Neid. Scrum-Berater haben eine universelle Antwort auf alle Fragen, etwa die eines Scrum-Masters in Ausbildung (SIP), parat. Insbesondere, wenn es konkret wird, und die Fragen mit “Wie” und “Wann” eingeleitet werden, lautet die Antwort stets “Frag das Team!”. Oft kommt sie prompt als wäre es das klarste von der Welt. Ich stelle ich mir den kleinen Yoda vor, wenn ich sie höre: “Das Team fragen Du musst.”. Und wenn Sie mir nicht glauben: Hier ist ein ein schönes Scrum FAQ online, das viele unterschiedliche Fragen, aber keine unterschiedliche Antworten parat hat. Es ist stattdessen eine Gruppenarbeit: “The questions are intended to be read and answered as a team.” Toll.

Das agile Team (v.l.n.r. Entwickler, Entscheider, Architekt) hat bestimmt eine Antwort ... Einfach fragen.

In einem Kundenworkshop zu Architekturdokumentation habe ich mich letztens dabei ertappt, eine ähnliche Strategie zu verfolgen wie die Scrum-Berater. Ich hatte auch eine universelle Antwort benutzt, die verblüffend oft auf in Diskussionen aufgeworfene Fragen passte. Sie lautete “Wenn es den Leser interessiert.” Mitunter wird so auch gleich die Schwäche in der Frage aufgedeckt, dass gar nicht genau klar ist, wer der Leser eigentlich ist. Eine 42 für Architekturdokumentation? (vgl. 42 bei Wikipedia)

7 Regeln für angemessene Dokumentation

Tatsächlich handelt es sich bei dieser Antwort übrigens um eine einfache Anwendung der 7 Regeln für angemessene Dokumentation. Sie werden im Buch Documenting Software Architectures vorgestellt, sind aber universell für Dokumentation gedacht. Hier sind sie komplett:

1. Schreibe Dokumentation aus Sicht des Lesers
2. Vermeide unnötige Wiederholungen
3. Vermeide Mehrdeutigkeit
4. Verwende eine Standardstrukturierung
5. Halte Begründungen fest
6. Halte Dokumentation aktuell, aber nicht zu aktuell
7. Überprüfe Dokumentation auf Gebrauchstauglichkeit

“Wenn es den Leser interessiert” ist eine Anwendung von Regel 1, und diese ist in der Praxis übrigens gar nicht so leicht zu befolgen, wie es auf den ersten Blick scheint. Das gilt für viele dieser Regeln.

Eine Architekturbeschreibung auf n Seiten, n < 30

Meiner Erfahrung nach wünschen sich viele Vorhaben ihre Architektur beschrieben in einem einzelnen Dokument, das vom Umfang her überschaubar ist. Die Seitenzahl sollte z.B. 30 DIN-A4-Seiten nicht überschreiten. Jeder Projektbeteiligte sollte das Dokument lesen (idealerweise von vorne nach hinten) und auch verstehen können; es manifestiert das gemeinsame Verständnis von der Softwarearchitektur. Dabei handelt es sich um genau so eine Art von Dokument, wie es entstehen soll, wenn Sie eine Vorlage wie z.B. arc42 benutzen (siehe Regel 4). Dass es sich dabei um eine verlockende Sache handelt, ist unstrittig.  Gleichzeitig ist die Erstellung aber schwierig, denn es drohen eine Reihe Fallen. Der Grund sind die besonderen Anforderungen:

• Die Zielgruppe ist heterogen
• Die Arbeitsergebnisse müssen sinnvoll linear angeordnet werden
• Informationen sollen nach Möglichkeit nicht redundant aufgenommen werden, das Dokument aber gleichzeitig leicht lesbar sein.

Und Sie sehen: Der erste Punkt macht die Anwendung von Regel 1 “Schreibe Dokumentation aus Sicht des Lesers” recht schwierig. Den Leser gibt es gar nicht.

Wirkungsvolle Architekturdokumentation

Dass die Regeln zwar sinnvoll klingen, ihre Anwendung in der Praxis aber ihre Tücken hat, habe ich in vielen Vorhaben erlebt. Denn ich beschäftige mich nun schon länger mit dem Thema Architekturdokumentation (zum Beispiel in meiner Kolumne im Java Magazin). Mit verschiedenen Projekten durfte ich gemeinsam Lösungen zu dem Thema erarbeiten.

Mittlerweile habe ich angefangen, meine Erfahrungen in einem Buch zusammenzuschreiben. Es soll den Lesern konkret anwendbare Hilfestellung bei ihrer Architekturdokumentation geben. Einfache Universalantworten habe ich aber nicht parat. Aber das Buch macht die sieben Regeln für gute Dokumentation durch praxiserprobte Werkzeuge und durchgängige, konkrete Beispiele erlebbar.

In diesem Blog möchte ich ab und über meine Fortschritte berichten. Bleiben Sie dran, über Feedback freue ich mich.