Wer eine Vorlage bzw. eine Gliederung zur Dokumentation einer Softwarearchitektur sucht, wird insbesondere im deutschsprachigen Raum zwangsläufig auf die arc42 stoßen. Die arc42 liefert nicht nur eine Struktur (und damit auch eine Vorgehensweise) zur Dokumentation von Softwarearchitektur, sondern auch noch unzählige Vorlagen in allen verschiedenen Dateiformaten.

Was bis jetzt leider gefehlt hat, war eine aktuelle Vorlage für Enterprise Architect. Bis jetzt, denn als langjähriger Nutzer von arc42 und Enterprise Architect habe ich eine Community Contribution erstellt.

In diesen Artikel möchte ich erklären, wie gewisse Abschnitte in Enterprise Architect umgesetzt sind bzw. wie sie verwendet werden können. Ich werde nicht auf die Inhalte der arc42 selbst eingehen. Dazu gibt es nämlich ausführliche Informationen auf der Website der arc42.

Über das Enterprise Architect-Template

Das Enterprise Architect-Template beinhaltet die komplette arc42-Struktur, basierend auf der Version 8.2 von Jänner 2023. Es werden nur Funktionen der Professional Edition von Enterprise Architect verwendet, um mit allen Versionen kompatibel zu sein. Die Umsetzung im Template verwendet UML-Diagramme bzw. Texte, wenn diese sich besser als Diagramme eignen. In einigen Abschnitten wie dem Glossar oder den Risiken werden erweiterte UML-Diagramme verwendet.

Download

Das Template kann hier heruntergeladen werden:

• arc42 V8 (DE) EAPX-Version (EA <16.x)
• arc42 V8 (DE) QEA-Version (EA >=16.x)
• arc42 V8 (EN) EAPX-Version (EA <16.x)
• arc42 V8 (EN) QEA-Version (EA >=16.x)

Eine Vielzahl von weiteren Formaten (nicht EA) findet man auf der Downloadseite von arc42.

Anmerkung zu den Enterprise Architect Versionen

Es werden QEA- und EAPX-Dateien zur Verfügung gestellt. QEA wurde mit der Version 16 von Enterprise Architect (EA) eingeführt und basiert auf SQlite3. EAPX ist das ältere Standardformat und verwendet JET 4 als Repository-Datenbank. Dieses Format wird von EA 15 und darunter unterstützt.

Bei Versionen früher als EA 14 muss die Dateiendung von EAPX auf EAP umbenannt werden. Vor Version 14 konnte sowohl JET 3.5 als auch JET 4 in EAP-Dateien verwendet werden. Mit Version 14 wurde diese Unterscheidung explizit gemacht, indem EAPX JET4 und EAP JET 3.5 verwendet.

Wenn ein Modell nur lesend verwendet wird, kann man die EA Lite Edition verwenden. Diese kann kostenlos heruntergeladen und verwendet werden.

Template verwenden

1. QAE- oder EAPX-Datei in der gewünschten Sprache (Deutsch oder Englisch) herunterladen.
2. Template an den entsprechend Zielort kopieren und umbenennen.
3. Optional (siehe „Anmerkung zu den Enterprise Architect Versionen“): Dateiendung von EAPX auf EAP umbenennen.
4. Datei öffnen.
5. Inhalte entsprechend der Bedürfnisse anpassen. Es sind alle offiziellen Erklärungen der arc42 als Notiz in den Diagrammen eingefügt. Wo notwendig, wurden zusätzliche Erklärungen eingefügt.
6. Das Paket „Info“ kann gelöscht werden, da es nur Metainformationen zum Template enthält.

Umsetzung der arc42 in Enterprise Architect

Nach dem Öffnen der Datei wird automatisch die Info-Seite aufgemacht. Das ist ein Paketdiagramm mit den Informationen zu arc42 sowie einem verlinkten Inhaltsverzeichnis. Dieses Paketdiagramm ist nicht Bestandteil von arc42 und kann bei Bedarf auch gelöscht werden.

Das Modell ist nach Paketen unterteilt. Jedes Paket entspricht dabei einem Kapitel der arc42-Vorlage. In jedem dieser Pakete gibt es ein Diagramm, das den Namen des Pakets trägt. Dieses Diagramm ist immer der Einstiegspunkt für das jeweilige Kapitel und sollte im Zweifelsfall deshalb als erstes geöffnet werden, um ein Kapitel zu erforschen.

Es befinden sich in allen relevanten Diagramme Notizen (Notes), die den Beschreibungstext der arc42-Hilfe beinhalten. Insbesondere findet man hier die Absätze „Inhalt“ und „Motivation“ der Hilfe wieder. Auf „Form“ wurde in der Regel verzichtet, da ich die Form durch das EA-Template bereits vorwegnehme.

Im Nachfolgenden erläutere ich die Umsetzung pro Kapitel.

Einführung und Ziele

Im ersten Kapitel gibt es zwei Text-Dokumente für Qualitätsziele und Stakeholder. Beide Dokumente beinhalten Tabellen. in denen jeweils die Qualitätsziele bzw. Stakeholder aufgelistet werden.

Anmerkung: Ab der Corporate-Edition von Enterprise Architect werden Custom Tables unterstützt, die anstelle der Dokumente direkt verwendet werden. Da die Profession-Edition aber keine Custom Tables unterstützt, habe ich stattdessen Text-Dokumente angelegt.

Zusätzlich gibt es hier ein Anwendungsfalldiagramm „Aufgabenstellung“. Dort kann die Aufgabenstellung in Form der wichtigsten Anwendungsfälle beschrieben werden. Sofern es weitere Anforderungsdokumente gibt, soll an der Stelle auf diese verwiesen werden.

In diesem ersten UML-Diagramm sehen wir auch, dass alle UML-Elemente im Template eine kurze Beschreibung haben. Ich empfehle das bei allen Elementen Ihres Modells zu machen. Diese Beschreibung muss (und soll) nicht lang sein, hilft aber ungemein, zusätzliches Verständnis für die Funktion des jeweiligen Elements zu erlangen. Wenn Sie sich das Template ansehen, werfen Sie auch immer einen Blick auf die Beschreibung der Elemente. Oft sind hier Tipps enthalten, wie man die jeweiligen Elemente am besten beschreiben kann.

Anforderungen können auch direkt in Enterprise Architect verwaltet werden. Dazu kann ein Requirements Diagram mit entsprechenden Requirements Elements angelegt werden. Das kann vor allem dann sinnvoll sein, wenn eine Traceability zu den Anforderungen benötigt wird.

Randbedingungen

Die Randbedingungen beinhalten lediglich ein Text-Dokument mit drei Tabellen für technische und organisatorische Randbedingungen sowie Konventionen. Die Konventionen werden in der Literatur auch als politische Randbedingungen oder Regularien bezeichnet. Die Unterteilung ist optional und kann auch weggelassen werden, falls gewünscht. In dem Fall hat man nur eine Tabelle mit allen Randbedingungen.

Auch hier gilt, dass statt den Text-Dokumenten auch Custom Tables verwendet werden können.

Kontextabgrenzung

Die Kontextabgrenzung ist unterteilt in eine fachliche und technische Kontextabgrenzung. Es wird hier ein Anwendungsfall- bzw. ein Verteilungsdiagramm verwendet. Beide Diagramme sind keine strikte UML, sondern etwas liberaler interpretiert. Hier wurde auf Genauigkeit verzichtet, um Diagramme zu erhalten, die für Stakeholder einfach zu lesen sind. Wer möchte, kann hier natürlich auch gerne exakte UML-Diagramme verwenden.

Für den fachlichen Systemkontext würde ich hierfür ein Paket verwenden, um das System darzustellen. Alternativ kann auch eine Boundary für das System verwendet werden. Beim technischen Systemkontext muss die System-Komponente durch einen Knoten ersetzt werden.

Wir können hier auch beobachten, dass Elemente wie Akteur-1 und Akteur-2 von der Aufgabenstellung wiederverwendet werden. Auch das System wird wiederverwendet und ist eigentlich unter Bausteinsicht/Komponenten abgelegt. Die Wiederverwendung von Modellierungsobjekten ist Best Practice und sollte auch bei allen Änderungen und Anpassungen des Templates im Kopf behalten werden.

Neben den fachlichen Kontext wird auch noch ein technischer Kontext definiert. Dieser wird für viele Systeme aber optional sein. Der Fachliche sollte jedoch in jedem System vorhanden sein.

Lösungsstrategie

In diesem Kapitel werden die grundlegenden Entscheidungen und Lösungsansätze, die das Systems prägen, beschrieben. Dies geschieht wieder in einem Text-Dokument.

Bausteinsicht

In der Bausteinsicht wird nun die Struktur des Systems beschrieben. Es werden die verschiedenen Bausteine, deren Beziehung zu einander und die Hierarchie modelliert. Im Template verwende ich dazu Komponentendiagramme. Es können aber auch andere Diagramme wie das Kompositionsstrukturdiagramm, das Paketdiagramm oder das Klassendiagramm geeignet sein. Wer mehr dazu wissen möchte, kann sich hier eine Zusammenfassung der wichtigsten UML-Diagramme für die Softwarearchitektur ansehen.

Die Bausteinsicht nimmt das System, welches wir in der Kontextabgrenzung bereits eingezeichnet haben, und erstellt Zerlegungen in mehreren Ebenen. Ebene 1 ist die Whitebox-Darstellung des Systems. Wir sehen die enthaltenen Bausteine (A, B, C) sowie die angebotenen und benötigen Schnittstellen (Recognition, Video).

Ausgehen davon können wir weiter in unser System hineinzoomen und die einzelnen Bausteine der Ebene 1 auf Ebene 2 genauer darstellen. Ich empfehle, für jeden Baustein ein eigenes Ebene-2-Diagramm zu erstellen. Die Diagramme sollten von Ebene 1 aus verlinkt werden. Das kann man beispielsweise über das Kontextmenü machen. Dazu klickt man mit der rechten Maustaste auf eine Komponente und wählt New Child Diagram->Add Diagram. Verlinkungen erkennt man an den Link-Symbol in der rechten unteren Ecke einer Komponente (siehe Komponente A).

Von Ebene 2 kann man auf Ebene 3 verlinken usw.. Man muss hier auch nicht immer bei Komponentendiagrammen bleiben. Gerade auf den detaillierteren Ebenen können sich beispielsweise Klassendiagramme besser eignen.

Laufzeitsicht

Nun können wir die dynamischen Aspekte des Systems in der Laufzeitsicht beschreiben. Im Template finden sich als Beispiel dazu ein Aktivitäts- und ein Sequenzdiagramm. Für weitere Möglichkeiten zur Beschreibung von Verhalten verweise ich wieder auf die wichtigsten UML-Diagramme für die Softwarearchitektur.

Auch hier können wir wieder sehen, dass Akteur-1 und Komponente A im Sequenzdiagramm wiederverwendet werden.

Verteilungssicht

Die Verteilungssicht beschreibt die physische Verteilung des Systems auf verschiedenen Rechnerknoten. Die UML bietet hier mit dem Verteilungsdiagramm ein geeignetes Modellierungstool. Wir sehen hier auf welchen physischen Knoten unsere Software verteilt ist. Auch externe Systeme können hier eingezeichnet werden, wobei die interessante Information vor allem der Kommunikationskanal zwischen unserem System und externen System ist.

Bei Verteilungsdiagrammen verwende ich gerne die <<manifest>>-Beziehung, um anzuzeigen, welche Komponenten durch welche Artefakte abgebildet werden. Das erlaubt, einen Zusammenhang zwischen Baustein- und Verteilungssicht herzustellen.

Querschnittliche Konzepte

Querschnittskonzepte können viele verschiedene Themen beinhalten, wie z.B. Fehlerbehandlung, Protokollierung (Logging), die Benutzeroberfläche, Sicherheit, das Domänenmodell, Persistenz, etc. Je nach Konzept können hier unterschiedliche Möglichkeiten zur Modellierung genutzt werden.

Im Template habe ich 3 Beispiele modelliert: Protokollierung, Fehlerbehandlung und Domänenmodell. Die ersten beiden Konzepte werden über Text-Dokumente beschreiben, das Domänenmodell wird über ein Klassendiagramm beschrieben. Häufig werden Sie hier textuelle Beschreibungen verwenden wollen. Wenn ein Diagramm sinnvoll ist, dann fügen Sie gerne eines hinzu, aber bitte nicht nur des Diagramms willens.

Architekturentscheidungen

Die Architekturentscheidungen sind eine Sammlung von einzelnen Text-Dokumenten, welche die jeweilige Entscheidung beschreibt. Durch Assoziationen zwischen diesen Dokumenten kann die Abhängigkeit der Entscheidungen dargestellt werden.

Innerhalb der Dokumente wird die folgende Struktur vorgeschlagen:

1. Fragestellung: Formulierung der eigentlichen Fragestellung ggf. mit Kontext, sofern hilfreich.
2. Relevante Einflussfaktoren: Auflistung relevanter Einflussfaktoren für diese Entscheidung.
3. Annahmen: Auflistung von Annahmen, die für diese Entscheidung getroffen werden mussten.
4. Alternativen: Gegenüberstellung möglicher Entscheidungsalternativen. Die Alternativen sollten hier bewertet werden, z.B. mithilfe einer Entscheidungsmatrix oder durch Auflisten von Vor- und Nachteilen. Umfangreiche Analysen (z.B. Gegenüberstellung der Kosten) sollten in eigenständigen Dokumenten gemacht und hier referenziert werden.
5. Entscheidung: Dokumentation der getroffenen Entscheidung. Eine Begründung kann ebenfalls hinzugefügt werden, falls dies für das Verständnis hilfreich ist.

Es können natürlich auch alternative Darstellungsformen wie Architecture Decision Records (ADR) verwendet werden.

Entscheidungen sollten immer ein Datum beinhalten, zu dem diese Entscheidung gemacht wurde, denn oftmals ist der zeitliche Zusammenhang einer Entscheidung wichtig für das Verständnis. Wenn Sie von der Entscheidung „Wir verwenden Visual Basic 6.“ lesen, wird das in 2024 Kopfschütteln verursachen, 1999 war das aber vielleicht eine nachvollziehbare Entscheidung.

Enterprise Architect führt ein Erstell- und Änderungsdatum für jedes Element mit. Dadurch ist jetzt Entscheidung zeitlich dokumentiert. Wenn Sie es bevorzugen, können Sie das Datum der Entscheidung auch explizit im Text festhalten.

Qualitätsanforderungen

Die Qualitätsanforderungen werden im Template als Qualitätsbaum dargestellt. Dazu wird ein Klassendiagramm mit Generalisierungsbeziehungen (Vererbung) verendet. Der Qualitätsbaum verfeinert den Begriff „Qualität“ weiter in Top-Level-Qualitäten (Zuverlässigkeit, Sicherheit, …), Bottom-Level-Qualitäten (Fehlertoleranz, Integrität, …) und Qualitätsszenarien. Ein Qualitätsszenario beschreibt ein konkretes Ereignis, das eintreten kann sowie eine Metrik, um das korrekte Verhalten hinsichtlich der Qualität zu messen.

Eine alternative Darstellung kann über das Mind Mapping von Enterprise Architect erzielt werden.

Risiken und technische Schuld

In diesem Kapitel finden wir ein Requirements-Diagramm mit Risk-Elementen. Jedes Risk-Element stellt ein konkretes Risiko bzw. eine konkrete technische Schuld dar, die eine entsprechende Beschreibung enthalten soll. Es ist auch möglich, einen Risikotypen in den Eigenschaften zuzuweisen.

Risikolisten sollten immer priorisiert sein. Dies kann im einfachsten Fall durch eine visuelle Reihung im Diagramm erreicht werden oder über Tags bei den Risk-Elementen. Im Risk Management Tool kann außerdem eine Gewichtung vorgenommen werden.

Glossar

Zu guter Letzt werden im Glossar alle wesentlichen fachlichen und technischen Begriffe erklärt. Im Template habe ich zwei getrennte Glossare für die Fachbegriffe und die technischen Begriffe angelegt. Wenn diese Unterscheidung nicht relevant ist, kann man auch einen gesammelten Glossar führen.

Aus dem Diagramm „Glossar“ sind die beiden Glossarkategorien verlinkt. Durch einen Doppelklick kommt man so bequem zu den Fachbegriffen bzw. den technischen Begriffen. Die Einträge des Glossars bestehen aus dem Begriff, der erklärt werden soll und einer Begriffsdefinition.

Jetzt mit der Umsetzung beginnen

Template herunterladen und schon kann man mit der Dokumentation seiner Architektur nach arc42 in Enterprise Architect beginnen! Da es bei der konkreten Umsetzung erfahrungsgemäß zu einigen Unklarheiten, Spezialfällen und Herausforderungen kommt, unterstütze ich gerne bei der Realisierung Ihrer Dokumentation.

Nehmen Sie einfach Kontakt mit mir auf und wir besprechen ausführlich, wie Ihr System am besten mit arc42 und Enterprise Architect dokumentiert werden kann.