arc42 und andere Dokumentationsvorlagen

Was arc42 ist

arc42 ist eine kostenlose Vorlage zur Beschreibung und Kommunikation von Softwarearchitektur, entwickelt von Gernot Starke und Peter Hruschka und seit 2005 in der Praxis im Einsatz. Sie ist unter einer Creative-Commons-Lizenz (Namensnennung – Weitergabe unter gleichen Bedingungen) veröffentlicht, in mehr als einem Dutzend Sprachen und in Formaten wie AsciiDoc, Markdown und Word, mit einer leeren Fassung und einer Fassung mit eingebauten Hilfetexten. Besonders verbreitet ist sie im deutschsprachigen Raum und in der iSAQB-Ausbildung, sie wird aber weltweit genutzt.

arc42 ist bewusst weder eine Methode noch eine Notation. Es sagt Ihnen nicht, wie Sie entwerfen sollen, und schreibt weder UML noch C4 noch einen anderen Diagrammstil vor. Es ist ein Satz von zwölf beschrifteten Schubladen: Für jede Art von Architekturinformation sagt es, wohin sie gehört, damit alle Lesenden wissen, wo sie suchen müssen, und alle Schreibenden wissen, was fehlt. Die Autoren sagen ausdrücklich, dass jeder Abschnitt optional ist; ein kleines System füllt vielleicht vier Abschnitte auf wenigen Seiten, ein großes alle zwölf auf vielen.

Die Vorlage baut auf Ideen aus diesem Kapitel auf. Ihre drei Sichten (Baustein-, Laufzeit- und Verteilungssicht) entsprechen weitgehend den SEI-Kategorien Modul, Komponenten und Konnektoren sowie Zuordnung und Kruchtens Entwicklungs-, Prozess- und physischer Sicht aus Sichten und Blickwinkel. In ihren Entscheidungsabschnitt gehören die Architecture Decision Records, in ihren Qualitätsabschnitt die Qualitätsszenarien aus Kapitel 2.

Die zwölf Abschnitte

Das Diagramm gruppiert die Abschnitte nach der Frage, die sie beantworten. Die Abschnitte 1 bis 3 legen Ziele und Grenzen fest: wofür das System da ist, was die Lösung einschränkt und wo das System endet. Abschnitt 4 nennt die grundlegenden Ideen der Lösung, und die Abschnitte 8 und 9 enthalten die Prinzipien und Entscheidungen, die für die ganze Lösung gelten. Die Abschnitte 5 bis 7 zeigen die Struktur aus drei Blickrichtungen. Die Abschnitte 10 bis 12 machen Qualität, Risiken und Vokabular explizit.

arc42 sparsam nutzen

Der häufigste Weg, mit arc42 zu scheitern, ist, es als Formular zu behandeln, das ausgefüllt werden muss: Zwölf Überschriften werden angelegt, jede wird mit irgendetwas gefüllt, und das Ergebnis ist lang, generisch und wird nie gelesen. Die Hinweise der Vorlage selbst weisen in die andere Richtung. Die arc42-FAQ sagt, es gebe keine allgemeine Regel für das Minimum, weil es von Kritikalität, Größe, Komplexität und Risiko abhängt, schlägt aber vor, dass selbst eine minimale Beschreibung drei bis fünf zentrale Qualitätsanforderungen als Szenarien, den Kontext und die externen Schnittstellen, eine kurze Lösungsstrategie, die Bausteinsicht der Ebene 1 und die wichtigsten querschnittlichen Konzepte enthalten sollte.

Vier Gewohnheiten halten arc42 schlank. Löschen Sie leere Abschnitte oder kennzeichnen Sie sie bewusst (Verteilung: eine einzige verwaltete Plattform; siehe Infrastruktur-Repository), damit Lesende wissen, dass die Lücke beabsichtigt ist. Verlinken statt kopieren: Die Anforderungen liegen im Backlog, die Entscheidungen im ADR-Ordner, die Verteilung im Infrastructure as Code; arc42 verweist darauf. Bevorzugen Sie Diagramme mit kurzen Elementtabellen gegenüber seitenlanger Prosa. Schreiben Sie für die Fragen der nächsten Lesenden, nicht für Vollständigkeit: Wenn niemand nach dem Laufzeitverhalten der Admin-Oberflächen fragen wird, beschreiben Sie es nicht.

arc42 lässt sich gut mit dem C4-Modell kombinieren. Eine gängige Paarung ist ein C4-Systemkontextdiagramm in Abschnitt 3, ein Containerdiagramm als Ebene 1 der Bausteinsicht in Abschnitt 5 mit Komponentendiagrammen als Ebene 2 und ein C4-Deployment-Diagramm in Abschnitt 7. Als Diagrams as Code im selben Repository wie der arc42-Text gepflegt, lässt sich die gesamte Beschreibung wie Code versionieren und prüfen.

Ausgearbeitetes Beispiel: arc42-lite für die Essenslieferplattform

Die folgende Seite ist eine vollständige arc42-lite-Beschreibung der Essenslieferplattform, die sich durch dieses Kapitel zieht. Sie passt auf eine gedruckte Seite plus Kontextdiagramm, beantwortet aber die Fragen, die eine neue Ingenieurin, eine Betriebsleitung oder ein Prüfer zuerst stellen würden, und verweist darauf, wo die Details liegen.

Weitere Vorlagen

Die SEI-Vorlage Views and Beyond. Das Software Engineering Institute veröffentlicht eine Dokumentationsvorlage, die Documenting Software Architectures: Views and Beyond von Paul Clements und Kollegen folgt. Ihre oberste Ebene hat sechs Teile: eine Roadmap und Übersicht der Dokumentation, den Architekturhintergrund, die Sichten, die Zuordnung zwischen den Sichten, referenzierte Materialien und ein Glossar mit Abkürzungen. Jede Sicht wird auf dieselbe Weise dokumentiert, mit einer primären Darstellung, einem Elementkatalog, einem Kontextdiagramm, einem Variabilitätsleitfaden und der Begründung (beschrieben im Kasten „Vertiefung“ in Abschnitt 4.2). Sie ist gründlicher als arc42 und eignet sich für große, langlebige oder vertraglich spezifizierte Systeme, bei denen jede Sicht vollständig und mit Querverweisen versehen sein muss; ihre Zuordnung zwischen den Sichten ist eine Stärke, die arc42 implizit lässt.

IEEE 1016. IEEE Std 1016-2009, Software Design Descriptions, legt Inhalt und Aufbau einer Software Design Description (SDD) fest, des detaillierten Entwurfsdokuments, das traditionell in Verteidigung, Luft- und Raumfahrt und anderen vertragsgetriebenen Projekten verlangt wird. Es übernahm die Begriffe Stakeholder, Anliegen, Blickwinkel und Sicht aus IEEE 1471 (dem Vorgänger von 42010) und listet Entwurfsblickwinkel wie Kontext, Komposition, logische Struktur, Abhängigkeiten, Information, Schnittstellen, Interaktion, Zustandsdynamik, Algorithmen und Ressourcen auf. IEEE setzte es 2020 auf den Status inactive-reserved, doch es wird weiterhin in Verträgen und in der Lehre zitiert, und ältere Programme liefern SDDs noch in dieser Form. Es steht dem Feinentwurf näher als der Architektur.

Designdokumente und RFCs, die viele Engineering-Organisationen verwenden, sind eine andere Art von Vorlage: ein Vorschlag für eine einzelne Änderung statt einer Beschreibung des ganzen Systems. Sie werden im übernächsten Abschnitt behandelt, Architektur kommunizieren.

Konformität mit ISO/IEC/IEEE 42010

ISO/IEC/IEEE 42010:2022 stellt Anforderungen an Architekturbeschreibungen und an Architekturbeschreibungsrahmen (ADFs): etablierte Konventionen wie arc42 oder den Ansatz Views and Beyond, mit denen in einer bestimmten Community Beschreibungen erstellt werden. Die Norm schreibt keine Vorlage, keine Notation und keinen Prozess vor. Eine Beschreibung ist konform, wenn sie die Informationen enthält, die die Norm verlangt, gleich welche Vorlage sie gliedert.

Grob gesagt bedeutet das: das beschriebene System und seine Umgebung benennen, die Stakeholder und ihre Anliegen benennen, angeben, welche Blickwinkel verwendet werden und welche Anliegen jeder abdeckt, Sichten liefern, die diesen Blickwinkeln folgen, Korrespondenzen festhalten (wie Elemente in verschiedenen Sichten zusammenhängen) und die Begründung für zentrale Entscheidungen festhalten. arc42 beansprucht keine Konformität von Haus aus, und einfachen arc42-Beschreibungen fehlt oft eine explizite Verbindung von jedem Anliegen zu der Sicht, die es behandelt. Die Lücken sind klein und leicht zu schließen, wie die Tabelle zeigt. Die meisten Teams brauchen keine formale Konformität; Teams in regulierten Branchen oder mit vertraglichen Pflichten manchmal schon, und es ist beruhigend, dass eine schlanke Vorlage die Norm mit wenigen Ergänzungen erfüllen kann.