Karriere
Wissen
Über uns
02. Feb 2026
Wie dokumentiert man Software effizient und verständlich? Wir haben von Gernot Starke gelernt, wie das arc42-Framework Struktur in Systeme bringt und die Kommunikation zwischen Engineers und Stakeholdern nachhaltig verbessert.
Dokumentation ist für viele Software Engineers ein rotes Tuch. Wir wissen zwar: Den geschriebenen Code in Prosa zu beschreiben, ist sinnvoll. Doch Zeitdruck oder das Gefühl, dass die Texte niemand liest, lassen diese Arbeit oft untergehen.
Kürzlich hatten wir die Gelegenheit, dieses Vorurteil gründlich zu entkräften: Die Koryphäe und Mitgründer von arc42 Dr. Gernot Starke hat uns in einem zweitägigen Workshop intensiv in die Welt der Architektur-Dokumentation eingeführt. Dabei lernten wir, dass effiziente Dokumentation kein Selbstzweck ist, sondern ein mächtiges Werkzeug für die tägliche Arbeit.
Um diese Effizienz in die Praxis umzusetzen, bietet arc42 einen klaren Leitfaden, der bei den fundamentalen Begrifflichkeiten der Softwarearchitektur ansetzt.
Architektur ist nicht nur im Gebäudebau ein Begriff, sondern auch in der Softwareentwicklung. Wenn man das Wort umschreiben möchte, landet man schnell bei der Formulierung «Etwas, das Struktur in ein System bringt». Doch was bedeutet Struktur? Gernot beschreibt sie sehr treffend als «das geordnete Gefüge der Bestandteile eines Systems sowie die Art und Weise, wie diese Bestandteile miteinander in Beziehung stehen».
Doch zur Architektur gehören auch Technologien, Konzepte und Methoden. Dies lässt sich gut am Beispiel eines Hochhauses veranschaulichen. Zur Technologie gehört unter anderem auch die Wahl der Baumaterialien. Mit Stahl und Beton kann man sehr hohe Gebäude bauen, mit Holz wird es schon deutlich schwieriger. Hierbei zeigt sich ebenfalls die Wechselwirkung zwischen Anforderungen. Während die Wahl auf Holz als struktureller Träger etwaige Umweltanforderungen erfüllen könnte, steht sie möglicherweise in Konflikt mit den brandtechnischen Anforderungen.
Dabei ist es wichtig, die Entscheidungen auf das Ziel auszurichten. Denn auch alle Toiletten und Duschen ins Erdgeschoss zu bauen hätte z.B. Struktur, erfüllt aber nicht den Zweck eines Apartmentkomplexes. Andererseits stehen häufig Ziele miteinander in Konflikt. So würde eine Reduktion der Anzahl Toiletten zwar das Budget optimieren, gleichzeitig aber auch die Anforderungen an Wohnraum nicht erfüllen.
Was das obige Beispiel gut zeigt, ist ein weithin bekanntes Problem: Schnittstellen zwischen Komponenten sind häufige Fehlerquellen. Dabei können die Komponenten verschiedene Systeme, Interfaces, aber auch Menschen sein. Während die Aufgabe aus Sicht des Sparbeauftragten umfänglich ausgeführt wurde, fehlt es ihm wohlmöglich an einer Gesamtsicht auf das Projekt. Was ihm für eine objektiv sinnvolle Erfüllung fehlte, war der weitere Blick auf die Lösungsanforderungen.
Wie man dieses Missverständnis beheben oder ihm gar vorbeugen könnte, ist wohl den meisten klar: Bessere Kommunikation. Doch wenn das so einfach ist, wieso klappt es dann so häufig nicht? Mit arc42 lernten wir eine Struktur kennen, welche genau diesen Austausch vereinfacht, indem sie Abstraktionslevels vorschlägt, nach denen man die Software und deren Architektur beschreiben kann.
Um unsere Aufgabe effizient erledigen zu können, müssen wir die Anforderungen an unseren Code sehr genau kennen. Leider enthalten Anforderungen oft implizite Annahmen, die wir nicht kennen können, da uns zum Beispiel das zugrundeliegende Fachwissen fehlt. Um dem entgegenzuwirken, lohnt es sich, dass wir uns dieser Probleme bewusst sind und diese teilweise nicht ersichtlichen impliziten Annahmen proaktiv suchen.
Dokumentation bringt einige Herausforderungen mit:
Es gibt jedoch einige Gründe, aus denen Dokumentation zu schreiben sinnvoll ist:
Im folgenden Kapitel werden die 10 Kapitel der arc42-Dokumentation vorgestellt. Es lohnt sich allerdings, genau zu überlegen, welche Teile für welche Zwecke geeignet sind, denn je nach Projekt gibt es für gewisse Kapitel tatsächlich niemanden, der es je lesen wird.
Die Dokumentation hält viele Lösungsansätze und Vorschläge zur Bewältigung der genannten Herausforderungen bereit.
Ein zentraler Punkt vorweg: arc42 ist in Erzählreihenfolge strukturiert. In der Praxis ist es üblich, dass die Kapitel in völlig anderer Reihenfolge geschrieben werden.
Hier werden die relevanten äusseren Einflüsse erläutert. Dies können zum Beispiel gesetzliche Vorgaben sein, aber auch Entscheidungen, die ausserhalb des Einflussbereichs des Projektteams getroffen wurden und jetzt nicht mehr geändert werden können.
Dieses Kapitel beinhaltet vor allem externe Schnittstellen, während das eigene Projekt als Blackbox behandelt wird. Am einfachsten lässt sich diese Abgrenzung in einem Diagramm darstellen. Im folgenden Diagramm wird dies anhand eines Projekts gezeigt, bei dem Krankenversicherungskarten im Auftrag der Versicherungen gedruckt werden sollen.
Ein solches Diagramm wird am besten immer, wie im Beispiel von einer Tabelle begleitet. So braucht das Diagramm nur kurze, stichwortartige Begriffe und bleibt sehr übersichtlich. Die einzelnen Bausteine werden in der Tabelle genauer erläutert, sodass sich die Informationen dennoch zu einem Gesamtbild zusammensetzen.
Diese Kombination von Diagramm und Tabelle hat zudem den Vorteil, dass Änderungen sehr einfach in die Tabelle eingepflegt werden können und nicht immer das ganze Diagramm erneuert werden muss.
Manchmal ist es gar nicht so einfach, das System genau abzugrenzen und zu entscheiden, was dazu gehört und was nicht. Hierbei gibt es meistens auch kein absolutes Richtig oder Falsch, sondern es ist vielmehr eine architektonische Frage, wo man die Grenze ziehen will.
Die Lösungsstrategie gibt die grosse Richtung vor, wie das Projekt aufgebaut werden soll. Hier sollten insbesondere ungewöhnliche Entscheidungen begründet werden («Wir generieren die Datenbankschemata erst zur Installationszeit, da die Anforderungen nicht im Vornherein bekannt sind»).
Das Ziel der Bausteinsicht ist, das Projekt auf verschiedenen Levels zu zeigen. Auf der Level-1-Sicht werden die Hauptbausteine des Projekts, ihre Schnittstellen dargestellt und die Interaktionen zu den externen Komponenten aufgezeichnet. Der Rahmen ist dabei meist durch die Blackbox der Kontextabgrenzung gegeben, welche man als Level-0-Sicht auffassen kann.
Dieses Prinzip kann rekursiv erweitert werden, theoretisch bis hinab zu einzelnen Klassen. In der Praxis lohnt es sich nur, so weit zu gehen, wie es für die Stakeholder relevant ist. Für Entwickler kann der genauere Aufbau des Codes in Kapitel "Konzepte" erklärt werden. Hier sollten lediglich die Informationen für einen Überblick beschrieben werden.
Genau wie bei der Kontextabgrenzung ist es empfehlenswert, zu jedem Diagramm eine Tabelle zu erstellen, die die Bausteine etwas genauer erklärt.
Diese Sicht beschreibt das konkrete Verhalten der Blöcke mittels Szenarien. Dies können wichtige Anwendungsfälle oder Features sein, aber auch Interaktionen an äusseren Schnittstellen, Starten und Beenden des Programms und Fehlerbehandlung.
Ähnlich wie die Tabellen für die Bausteinsicht sollten die einzelnen Verhalten noch in 1-2 kurzen Sätzen beschrieben werden.
Auf dieses Thema sind wir nur kurz eingegangen. Hier wird der Aufbau des fertigen (verteilten) Projekts aufgezeigt. Beispielsweise wird hier die technische Infrastruktur beschrieben (AWS oder steht der Server im Keller?).
Dies ist der Ort für die genauen Beschriebe der Komponenten. Dieses Kapitel ist für andere Entwickler gedacht, die sich in das Projekt einarbeiten. Denk dran: das beinhaltet auch dich in der Zukunft, wenn du dich nicht mehr an alle Details erinnern kannst. Gerade, wenn man an mehreren Projekten gleichzeitig arbeitet, kann dies sehr schnell gehen.
Du kannst hier die verwendeten Technologien und Methoden erklären sowie Links ins Repo und zum Sourcecode einfügen.
Entscheidungen zu dokumentieren, kann in mehreren Situationen hilfreich sein. Zum Beispiel ein Kollege, der ein Meeting verpasst hat.
Um Entscheidungen zu dokumentieren, ist das «ADR»-Prinzip sehr nützlich. Es steht für «Architecture Decision Record» und bietet ein Template, um die Entscheidungen zu verschriftlichen. Es beinhaltet die folgenden Teile:
Die ADRs können zum Beispiel gleich im Repository in einem Ordner Documentation/ADR abgelegt werden und sind so immer für alle einsehbar.
Fun Fact: es gibt sogar ein Kommandozeilenprogramm, das direkt ein Template im Markdown-Format erstellt.
Qualitätsmerkmale sind in der Architektur das, was am Schluss darüber entscheidet, ob ein System im Alltag funktioniert. Deshalb ist es wichtig, dass die Merkmale so formuliert sind, dass alle dasselbe darunter verstehen.
Doch wie macht man das? Eine Methode dazu ist SMART. Es steht für
Diese Qualitätsmerkmale können spezifisch zu gewissen Features gehören und über das ganze Projekt gesehen sehr unterschiedlich sein (ein Autoradio hat deutlich länger Zeit aufzustarten als der Airbag).
Unter quality.arc42.org finden sich 189 (Stand 16.1.26) mögliche Merkmale in einem interaktiven Graphen, der verwandte Merkmale verbindet.
Als extreme Zusammenfassung der bisherigen Kapitel kann man auch den sogenannten Architecture Communication Canvas nutzen. Dieser Steckbrief gibt einen kompakten Überblick über Stakeholder, Kontext und grobe Lösungsstrategie und dient dazu, schnell ein gemeinsames Verständnis aufzubauen.
Zudem kann dieser Canvas als Grundlage genutzt werden, um zu entscheiden, wo Bedarf nach genauerer Dokumentation besteht. Dies kann zum Beispiel bei Schnittstellen zwischen separaten Entwicklerteams der Fall sein, die erst aufgedeckt werden, wenn alles Teams bekannt ist, woran die anderen genau arbeiten.
Das Template kann man unter diesem Link in verschiedenen Formaten (Power Point, Miro, draw.io, PDF, …) herunterladen.
«Management is too important to leave it only to managers».
Aus diesem Grund lohnt es sich auch für Entwickler, etwas von Anforderungen (Requirements) zu verstehen. Solange wir Softwareentwickler unvollständige oder unpräzise Anforderungen erhalten, können wir keinen Code schreiben, der perfekt auf das Projekt passt. Dieses Kapitel zeigt einige Möglichkeiten auf, wie die Entwicklungsteams die Anforderungen verbessern können.
Für alle Unterkapitel gilt der folgende Grundsatz. Falls Informationen fehlen, überlegt euch zuerst (evtl. mit eurem Team zusammen), wie ihr die Fragen beantworten würdet. Geht dann auf den Requirement Engineer zu und vergleicht eure Sichtweise mit dessen/deren Vorstellung. Die Vorbereitung bietet eine gute Diskussionsgrundlage und kann implizite Annahmen aufdecken.
Ein wichtiger Schritt dazu ist, das Ziel des Projektes zu verstehen. Dazu kann der «Business Model Canvas» verwendet werden. Er wird anhand des Beispiels airbnb in der folgenden Grafik vorgestellt.
Der Masterplan hilft dabei, die Ziele auf konkrete Funktionen herunterzubrechen. Dies wiederum ermöglicht es, neue Ideen einzuordnen (oder wegzulassen, wenn sie nicht auf ein Ziel ausgerichtet sind).
Zuoberst kann eine Vision stehen, die grob beschreibt, was erreicht werden soll. Gerade bei kleineren Projekten ist die Vision äquivalent zum Ziel. Aus der Vision können Ziele abgeleitet werden. Die Hierarchie sorgt dafür, dass man nicht sofort in einzelne Tickets springt, sondern erst die Richtung klärt: Ziele → grobe Anforderungen („Prozesse“) → mittlere Granularität → feine Anforderungen/Funktionen.
Aus den Zielen leitest du dann grobe Anforderungen ab, die eher den End-to-End-Nutzen beschreiben (z. B. „Event registrieren“, „Account & Profil einrichten“). Erst darunter werden daraus konkrete Funktionen: Welche Schritte braucht es, welche Daten werden erfasst, welche Varianten müssen unterstützt werden?
Der praktische Vorteil: Neue Ideen landen nicht mehr als ungeordnete „Bäume“ im Backlog, sondern werden gegen die Ziel-Ebene geprüft. Passt eine Idee zu keinem Ziel, ist sie entweder „nice to have“ (und wird bewusst depriorisiert) oder ein Signal, dass ein Ziel fehlt bzw. falsch geschnitten ist.
Auf jeder Stufe können dabei Qualitätsanforderungen gemäss Kapitel 10 der arc42-Dokumentation gefordert werden, die dann für den ganzen Unterbaum erfüllt werden müssen.
Der Workshop lässt sich für mich in zwei kurzen Sätzen zusammenfassen:
Das arc42-Framework bietet für beides eine hervorragende Grundlage, wie man diese beiden Ziele erreichen kann. Denn die Kommunikation führt nur zum Ziel, wenn alle die gleiche Sprache sprechen.
Danke für Ihr Interesse an Cudos. Ihre Angaben werden vertraulich behandelt – den Newsletter können Sie jederzeit abbestellen.