Stefan Zörner
26.07.2024
arc42, der Dokumentationsvorschlag für Softwarearchitektur, hat sich zu einer Art De-Facto-Standard entwickelt. In diesem Beitrag tritt er gegen einige Alternativen an.
Habt ihr “King Kong vs. Godzilla” gesehen? Oder “Alien vs. Predator” (Teile 1 und 2)? Oder “Dracula vs. Frankenstein” (Deutscher Titel: “Draculas Bluthochzeit mit Frankenstein”)? Dieser Beitrag liefert etwas sehr Ähnliches: nur ohne Monster.
arc42 vs. … ja gegen was eigentlich? Oder ist arc42 etwa alternativlos?
Einblicke in Entwicklungsvorhaben und Rückmeldungen aus Workshops oder auf Konferenzen zeigen mir: arc42, der Dokumentationsvorschlag für Softwarearchitektur, hat sich zumindest im deutschsprachigen Raum zu einer Art De-Facto-Standard entwickelt.
Für die hohe Bekanntheit und Verbreitung gibt es unterschiedliche Gründe, ganz unabhängig davon, ob arc42 nun tatsächlich „pragmatisch, praktisch, gut“ ist – oder nicht:
Gleichwohl kommen regelmäßig – beispielsweise bei flächendeckenden Einführungen von arc42 in großen Unternehmen – immer wieder Fragen in zwei Richtungen auf:
Die zweite Frage ist insbesondere dort anzutreffen, wo Dokumentationen in Englisch verfasst werden, ggf. gemeinsam mit nicht-deutschsprachigen Team-Mitgliedern oder Kooperationspartnern. Anders als in D-A-CH, ist arc42 trotz verfügbarer englischer Übersetzung und mittlerweile auch vorhandener Sekundärliteratur z.B. in den USA wenig bekannt.
In diesem Blog-Beitrag stelle ich eine interessante Alternative zu arc42 vor und vergleiche die beiden Ansätze miteinander. Damit könnt ihr zumindest die Frage „Gibt es Alternativen?“ mit „Ja“ beantworten und hättet bereits Unterschiede und Gemeinsamkeiten parat. Letztere überwiegen (Spoiler-Alarm).
Viele Leute draußen im Feld setzen arc42 immer noch mit dem Wordtemplate aus 2005 gleich („arc42? Kenn ich. Da muss man dieses Word-Dokument ausfüllen“). Wohlwollendere sehen in arc42 eine Herangehensweise, um Softwarearchitektur methodisch zu entwickeln, und das Template ist “nur” die Ablagestruktur für Arbeitsergebnisse. Also eine Art Vorgehensmodell für Architekturentwürfe.
Ich selbst sehe in arc42 in erster Linie einen Vorschlag, um Architekturbeschreibungen, ganz gleich ob Vortrag, Foliensatz oder Dokument, zu gliedern. Eine Art Ablagesystem für Zutaten einer Architekturdokumentation inkl. einer sinnvollen (Lese-) Reihenfolge. Wobei ihr bei Weitem nicht immer alle Elemente der Gliederung (immerhin 12 Kapitel, siehe Abbildung 1 unten) benötigt.
In Softwarevorhaben und Workshops höre ich immer wieder das Argument „Der Quelltext ist die beste Dokumentation“. Meist von Entwicklerinnen und Entwicklern. Ich könnte den Leuten unterstellen, dass sie zu faul zum Dokumentieren sind. Stattdessen ist hier der Hinweis angebracht, dass der Code – obschon er wertvolle Informationen trägt – nicht die ganze Geschichte erzählt. Die bloße Verwendung einer bestimmten Technologie („Wir benutzen das Spring Framework“) beispielsweise, brauche ich tatsächlich nicht dokumentieren. Das sehe ich der Lösung (Code, Build-Files) in der Regel an. Was ich wiederum der Lösung nicht ansehe: Warum benutzen wir das Spring Framework? Hatten wir Alternativen erwogen? Welche Kriterien haben wir zur Entscheidung herangezogen? Oder war es eine Randbedingung?
“The code doesn’t tell the whole story.” (Simon Brown in “Software Architecture for Developers”)
Genau hier setzt Simon Brown mit dem Buch “Software Architecture for Developers” an. Sein Ansatz ist sehr pragmatisch, spricht Entwicklerinnen und Entwickler an und ist auch im englischsprachigen Raum gut vorzeigbar. Simon Brown schlägt in seinem Buch Dinge vor, die den Quelltext um wichtige Informationen ergänzen. Die folgende Abbildung zeigt seine “Zutaten” im Überblick:
Das Ganze fasst Simon Brown in Anlehnung an einen Reiseführer als Software Guidebook zusammen. Das Ergebnis ist ebenfalls ein Gliederungsvorschlag für Architekturbeschreibungen. Mithin ein interessanter Kombattant für arc42 …
Dabei schätzt Simon Brown die Zutaten als unterschiedlich wichtig ein. Dinge, die er laut eigener Aussage niemals weglässt, sind oben in der Liste mit (*) markiert.
Finden sich die von Simon Brown vorgeschlagenen Elemente in der Struktur von arc42 wieder? Ja, tun sie. Die folgende Tabelle gibt für jedes Kapitel aus dem Software Guidebook einen passenden Ort in arc42 an (Alternativen in Klammern).
In vielen Punkten liegen direkte Entsprechungen vor (Beispiele: Constraints/Randbedingungen, Context/Systemkontext). An anderen Stellen gehört für eine Zuordnung ein bisschen methodisches Wissen und Kenntnis der beiden Ansätze dazu. So lassen sich übergreifende Architekturprinzipien in arc42 meiner Erfahrung nach am besten in der Lösungsstrategie (Abschnitt 4.) unterbringen. Nüchtern betrachtet sind die beiden Ansätze allerdings recht ähnlich. Ein Mapping in anderer Richtung (arc42-Schnipsel im Guidebook von Simon Brown „abheften“) ist ebenso möglich.
Bei vielen Zutaten lassen sich also “Orte” in der jeweils anderen Gliederung finden. So gesehen, sind die Unterschiede gar nicht groß und liegen eher in den Ansätzen selbst. Ich nenne zwei konkrete Beispiele: Sichten und Qualitätsszenarien.
arc42 ist von klassischer Softwarearchitektur inspiriert und beinhaltet in guter Tradition zu IEEE 1471 verschiedene Sichten (Englisch: “Views”): Bausteinsicht, Laufzeitsicht, etc. Simon Brown hingegen strapaziert den Sichtenbegriff nicht sonderlich – im Gegenteil (eine Kapitelüberschrift bei ihm: Beware of the “views”). Er schlägt aber auch Diagramme zur Visualisierung bestimmter Aspekte vor und kritisiert vor allem dogmatische Diskussionen nach dem Motto: „Was gehört in welche Sicht?“.
Qualitätsszenarien (Synonym: Bewertungsszenarien) als Konkretisierung von Qualitätszielen haben in arc42 einen festen Platz. Dabei handelt es sich, wie bei den Sichten um ein klassisches Werkzeug der methodischen Softwarearchitektur. Hier konkret der qualitativen Architekturbewertung. Simon Brown verbietet keine Qualitätsszenarien, legt diese aber auch nicht nahe und erwähnt sie auch nicht. Am ehesten passt dieses Element im Guidebook bei den „Qualitity Attributes“. Und da tue ich es auch hin, wenn ich das Guidebook als Struktur in Projekten verwende.
Diátaxis geht auf Daniele Procida zurück und stellt einen systematischer Ansatz für technische Dokumentation dar. Er ist allgemein und bezieht sich nicht nur auf Software.
Diátaxis identifiziert Bedürfnisse unterschiedlicher Zielgruppen, schlägt passende Formen der Dokumentation vor und ordnet diese in Quadranten ein. Abb. 4 stellt diese Kategorisierung in einer Art Kompass dar.
Ein Tutorial ist dabei eine Art Unterrichtseinheit und lernorientiert. Ein How-to Guide ist demgegenüber eine Anleitung, die durch ein Problem oder zu einem Ergebnis führt. How-to Guides sind zielorientiert.
Als eine “Explanation” bezeichnet Daniele Procida die Auseinandersetzung mit einem Thema, die ein Nachdenken ermöglicht. Solche Erörterungen sind verständnisorientiert. Auf der anderen Seite sind Referenzen technische Beschreibungen der Maschinerie und ihrer Verwendung. Referenzhandbücher sind informationsorientiert.
Das Diátaxis-Modell ist nicht nur klug durchdacht und interessant aufbereitet. Es stellt auch eine sinnvolle Ergänzung zu arc42 dar, da es zum einen weitere technische Dokumentation motiviert und einordnet, die gerade nicht in eine Architekturbeschreibung hineingehört. Weiterhin hilft es bei der Fokussierung der übergreifenden Konzepte in Abschnitt 8 von arc42, die in der Praxis leider nicht immer zielgruppenorientiert geraten.
Ein in den letzten Jahren immer mehr ins Rampenlicht geratener Dokumentationsansatz ist C4, ebenfalls von Simon Brown. Die vier Cs in C4 stehen für Context, Containers, Components, and Code. C4 stellt eine Menge von Abstraktionen zur Strukturierung von Softwaresystemen mit graphischen Mitteln dar.
Ganz grob beginnt der Ansatz mit dem System als Black Box und zoomt bis in den Quelltext hinein. Tatsächlich ist es weniger eine Alternative zu arc42 als zu Sichten in UML. Mit arc42 lässt es sich im Rahmen einiger der dort enthaltenen Sichten sogar prima kombinieren (in der Reihenfolge: Systemkontext, Verteilungssicht, Bausteinsicht).
Alle gezeigten Strukturierungsansätze geben gute Hinweise, welche Aspekte eurer Softwarearchitektur ihr festhalten solltet, um die Lösung (auch später noch) gut kommunizieren zu können.
Insbesondere arc42 und das Software Guidebook helfen bei der Strukturierung von Architekturbeschreibungen. Beide Vorschläge müsst ihr auf eure Projektsituation anpassen. Insbesondere, wenn es sich nicht um ein Informationssystem im klassischen Sinne handelt, sondern stattdessen um eine Systemlandschaft, eine sehr große Anwendung, eine Produktfamilie oder ein eingebettetes System.
Dokumentation ist kein Selbstzweck. Das eigentliche Ziel, die Lösung nachvollziehbar festzuhalten, lässt sich mit arc42 ebenso wie mit dem Software Guidebook erreichen. Die große Überdeckung der beiden Ansätze lässt vermuten, dass ähnliches Erfahrungswissen dahintersteckt. Nutzt es zumindest als Inspiration und Anregung, bevor ihr euch eigene Inhalte und eine völlig neue Gliederung für eure Softwarearchitekturbeschreibung ausdenkt!
Anmerkung: Dieser Beitrag ist in einer ersten Fassung 2014 im damaligen Blog des Hanser-Fachbuchverlages erschienen. Ich habe ihn in der Zwischenzeit aktualisiert sowie um Inhalte wie C4 und Diátaxis ergänzt und führe ihn hier fort.