Stefan Zörner
18.02.2016
Abheften für Fortgeschrittene. Hier arbeite ich die Unterschiede der beiden Abschnitte 8 und 9 in arc42 heraus. Und als Bonus auch noch die zu Abschnitt 4. Irritiert? Dann weiterlesen ...
arc42 ist als Gliederung für Architekturbeschreibungen von Softwaresystemen weit verbreitet, zumindest in D-A-CH. Entsprechend treffe ich häufig auf Projekte, die arc42 benutzen oder beabsichtigen dies zu tun. Im Praxiseinsatz erlebe ich typische Fragestellungen und die immer gleichen Stolperfallen. In diesem Beitrag beschreibe ich kurz, wie ich in Projekten mit einer besonders häufigen Unsicherheit umgehe.
arc42 ist zuallererst eine Strukturierungshilfe. Es weist Inhalten Ihrer Dokumentation einen Ort zu, wo Sie diese „abheften“. Viele Projekte tun sich schwer, bei einem Lösungsansatz zu entscheiden, ob er besser in Abschnitt 8 (“Konzepte”) oder 9 (“Entwurfsentscheidungen”) passt. Oder in beide? Die Abbildung rechts zeigt die Struktur von arc42 als Inhaltsverzeichnis.
Generell rate ich davon ab, arc42 als Dokument (z.B. in Word) auszufüllen. Sie fahren besser damit, Zutaten Ihrer Dokumentation einzeln anzufertigen und sie später zielgruppengerecht in unterschiedlichen Formen zu rekombinieren. Entsprechend spreche ich im Folgenden nicht davon, wo Sie etwas “eintragen” oder “reinschreiben” in arc42, sondern wo so eine Zutat oder auch ein Schnipsel (z.B. eine Architekturentscheidung oder ein Konzept) ihren Platz findet.
Für die Einordnung von Entscheidungen, Konzepten sowie für die meiner Meinung nach eng verknüpfte Lösungsstrategie hilft die folgende Tabelle weiter. Ich führe die Inhalte im Folgenden weiter aus.
 |
 |
 |
|
| arc42-Abschnitt | 9. Entscheidungen |
8. Konzepte |
4. Lösungsstrategie |
| Anzahl pro System | mehrere, eine pro wichtiger Fragestellung | mehrere, eins pro wichtigem Thema | eine verdichtete Übersicht, z.B. als Tabelle |
| Zielsetzung | Nachvollziehbarkeit einer Entscheidung | breite Kommunikation eines Lösungsansatzes | Brückenschlag von Architekturtreibern zu Lösungsansätzen |
| Leitfrage | Warum haben wir uns so entschieden? | Wie gehen wir mit dem Thema um? | Wie sieht die Lösung grundsätzlich aus? |
| Typische Form | Prosa, stets gleich strukturiert, knapp, häufig mit Kreuztabelle | Prosa, ergänzt mit Abbildungen und (Quelltext-)Beispielen | Tabelle (Spalten: Ziel, Ansätze), ggf. ergänzt mit einem Überblicksbild |
Eoin Woods versteht Softwarearchitektur recht dramatisch als Summe der Entscheidungen, die – wenn falsch getroffen – Ihr Projekt scheitern lassen können. Diese Architekturentscheidungen ändern Sie im weiteren Verlauf nur schwer (oder es wird zumindest teuer); sie wirken breit.
Bei Architekturdokumentation geht es vor allem darum solche Entscheidungen nachvollziehbar festzuhalten. Im Nachhinein ist das schwieriger als beim Entscheiden. Deshalb nutze ich die gleichen Werkzeuge zum Treffen und zum Festhalten der Entscheidung – die Dokumentation fällt dann quasi ab.
Zum Festhalten einer Entscheidung gehören für mich zumindest eine konkrete Fragestellung (z.B. eine Technologie-Auswahl, Make-Or-Buy …), betrachtete Alternativen und Bewertungskriterien. Kreuztabellen helfen dabei, Argumente verdichtet darzustellen.
Pro Entscheidung fertigen Sie ein einzelnes schlankes Dokument an oder eine einzelne Wiki-Seite oder ein … (das ist jetzt eine Toolfrage). Jede Entscheidung strukturieren Sie dabei gleich. Meine Empfehlung dazu in Kurzform: Fragestellung, Einflussfaktoren, Annahmen, Alternativen, Entscheidung. Am Ende dieses Beitrags finden Sie weiterführende Links dazu, Beispiele inklusive.
Entscheidungen treffen Sie und Ihr Team, um unter gegebenen Rahmenbedingungen Ziele zu erreichen. Auch Konzepte verfolgen Ziele und sind Teil Ihrer (Architektur-)Lösung. Dieser Umstand macht die Verwirrung aus, wo man was abheftet in arc42.
Meine Auslegung: Während Entscheidungen eine Frage beantworten, diskutiert jedes Konzept ein Thema. arc42 schlägt im betreffenden Abschnitt 8 als Unterkapitel viele solcher Themen vor: Persistenz, Sicherheit, … Der zentrale Unterschied aus meiner Sicht: Während es bei den Entscheidungen vor allem um die Nachvollziehbarkeit geht ("Warum haben wir uns so entschieden?"), kommunizieren Konzepte vor allem Dinge, die innerhalb Ihres Softwaresystems übergreifend gelöst sind ("Wie gehen wir mit einem bestimmten Thema um?").
Die Zielgruppe eines Konzeptes sind Team-Mitglieder, die das Konzept in ihren Systemteilen anwenden und/oder umsetzen. Entsprechend haben Konzepte idealerweise Tutorial-Charakter und sind mit Beispielen gespickt. Auch für Konzepte schlage ich gern eine an das 4-Quadranten-Modell angelehnte gleichförmige Struktur vor. Sie ist freier als bei Entscheidungen, und gliedert ein Konzept nur grob vier Teile (Warum? Was? Wie? Wohin noch?), nicht feste Kapitel.
Übrigens löst eine Architekturentscheidung gerne das Anfertigen eines Konzeptes aus. In der Entscheidung beschreiben Sie, warum Sie sich für einen Architekturstil oder eine Technologie entschieden haben (Beispiel: Einsatz von Microservices, Verwendung von AngularJS). In Konzepten beschreiben Sie dann Dinge, die übergreifend für alle Services sind, bzw. wie Sie das UI bauen (die Entscheidung für AngularJS lässt einigen Spielraum …)
Ein oft vernachlässigtes Kapitel in arc42 ist Abschnitt 4 (“Lösungsstrategie”). Ich nutze es gerne um die Brücke zu schlagen zwischen den architekturrelevanten Anforderungen auf der einen Seite (Abschnitte 1-3 in der arc42-Gliederung) und der Lösung auf der anderen.
Besonders explizit geht dies in einer Tabelle, in der Sie in einer Spalte die Architekturtreiber (z.B. Ihre Qualitätsziele) auflisten, und diesen in der rechten Spalte Lösungsansätze zuordnen. Diese Lösungsansätze können Architekturprinzipien sein, der zugrunde liegende Stil, verwendete Muster, Technologieentscheidungen, Konzepte … In der Tabelle nennen Sie diese nur, und verweisen auf die betreffenden Schnipsel. Die Lösungsstrategie zeigt auf, mit welchen Ansätzen Sie den Qualitätszielen begegnen, und motiviert die Architektur so bereits auf oberster Ebene.
Das Problem mit dem Einordnen ist besonders gravierend wenn ein Projekt die Architektur nachdokumentiert, Zutaten also nachträglich anfertigt. Bei einem methodischen Vorgehen fallen die Schnipsel auf dem Weg ab und fügen sich nach und nach zu einer Architekturvision und später zu einem konsistenten Lösungsbild.
Zum Abschluss noch die versprochenen Links für Strukturierunsvorschläge, Beispiele inklusive. In meiner Blog-Serie arc42-Starschnitt finden Sie Beiträge zu allen drei genannten Abschnitten:
Die Leseprobe meines Buches zu Architekturdokumentation behandelt Architekturentscheidungen und die Lösungsstrategie ebenfalls, auch mit Beispielen (“Kapitel 3: Entscheidungen treffen und festhalten” als PDF hier herunter zu laden).