| Typ | Konzept |
|---|---|
| Quellen | Quelle - Effektive Softwarearchitekturen Quelle - Recherche - Softwarearchitektur heute 2026 |
| Erstellt | 2026-09-27 |
| Aktualisiert | 2026-09-27 |
| Tags | softwarearchitektur, dokumentation, arc42, sichten, vorlage |
Frei verfügbare Vorlage zur Dokumentation von Softwarearchitekturen, entwickelt von Peter Hruschka und Gernot Starke. Sie gliedert eine Architekturbeschreibung in 12 Abschnitte von den Zielen über Kontext, Bausteine, Laufzeit und Verteilung bis zu Konzepten, Entscheidungen, Qualität, Risiken und Glossar.
Die 12 Abschnitte
Die Gliederung stammt aus Tabelle 5.2 des Buches (Quelle - Effektive Softwarearchitekturen, S. 151–152):
| Nr. | Abschnitt | Inhalt |
|---|---|---|
| 1 | Einführung und Ziele | Aufgabenstellung, die 5–10 wichtigsten Qualitätsziele mit Mengengerüst, Stakeholder |
| 2 | Randbedingungen | technische, organisatorische, juristische Einschränkungen, Standards |
| 3 | Kontextabgrenzung | fachlicher und technischer Kontext, externe Schnittstellen |
| 4 | Lösungsstrategie | die zentralen Lösungsansätze in Kurzform |
| 5 | Bausteinsicht | statische Zerlegung, abwechselnd Black- und Whitebox, Ebene für Ebene |
| 6 | Laufzeitsicht | Zusammenspiel der Bausteine in wichtigen Szenarien |
| 7 | Verteilungssicht | Hardware, Netze, Betriebssysteme, Middleware |
| 8 | Querschnittliche Konzepte | Persistenz, Fehlerbehandlung, Logging, Transaktionen, Oberfläche, Integration … |
| 9 | Entwurfsentscheidungen | wichtige Entscheidungen mit Gründen und verworfenen Alternativen |
| 10 | Qualitätsszenarien | Qualitätsbaum und Szenarien (Softwarequalität) |
| 11 | Risiken | bekannte Risiken und technische Schulden |
| 12 | Glossar | die wichtigsten Begriffe |
Sichten
Vier Arten von Sichten zeigen dasselbe System für verschiedene Leser (S. 157):
- Kontextsicht: das System als Blackbox mit Nachbarsystemen und Benutzern. Fachlicher Kontext (welche Daten) und technischer Kontext (welche Kanäle und Protokolle).
- Bausteinsicht: Das System wird hierarchisch zerlegt. Eine Blackbox beschreibt Zweck, Schnittstellen, Ablageort im Code und offene Punkte. Eine Whitebox zeigt das Innere eines Bausteins mit seinen enthaltenen Blackboxes.
- Laufzeitsicht: Abläufe als Sequenzdiagramm oder nummerierter Text. Das Buch zeigt beide Formen für denselben Ablauf (S. 395–396).
- Verteilungssicht: Welcher Baustein läuft auf welcher Infrastruktur?
Regeln dafür: so wenig Formalismus wie möglich, so viel wie nötig. Riskante Teile ausführlich dokumentieren, harmlose knapp. Wiederkehrende Themen einmal als querschnittliches Konzept beschreiben (S. 157).
Grundsätze guter Dokumentation
- Aus Sicht der Leser schreiben, in ihrem Vokabular. Dokumente werden häufiger gelesen als geschrieben (S. 148).
- Das Warum dokumentieren, samt verworfener Alternativen, dazu Annahmen und Voraussetzungen.
- DRY / Single Point of Truth, kontrollierte Redundanz nur für bessere Lesbarkeit; keine Überraschungen (POLA).
- Aktuell, zielgruppengerecht, verständlich, wartbar, kompakt, hierarchisch organisiert (S. 146).
- Diagramme brauchen eine Legende; ein Diagramm sollte nur etwa 7 ± 2 Elemente zeigen. Unfertiges kennzeichnen („TBD“).
- Ergänzende Dokumente: Programmers' Daily Reference Guide, Architekturüberblick (höchstens 20–30 Seiten), Dokumentationsübersicht, Übersichtspräsentation, Architekturtapete als grosses Poster (S. 150–153).
Beispiele aus dem Buch
Kapitel 12 dokumentiert zwei echte Systeme nach arc42:
- M&M (Migration von Massendaten, um 2002/2003): 20 Millionen Kunden- und Kontodaten einer Finanzfirma von Mainframe-Dateien (VSAM, EBCDIC) in ein Java-Objektmodell. Qualitätsziele: Migration in höchstens 24 Stunden und revisionssichere Korrektheit. Lösung: Pipes-und-Filter mit einer Datenbank als Pipe und parallelen Regelprozessoren (Architekturstil). Die Fehlertabelle durfte höchstens 5000 Fälle enthalten, weil 200 Personentage à 25 Fälle für die Handarbeit bereitstanden (S. 360–376).
- MaMa (Massenmarkt, ab 2004): eine Plattform für CRM-Kampagnen zwischen Mandanten (etwa Mobilfunkanbietern), Partnern (Druckerei, Scandienst, Callcenter) und Endkunden. Hauptziel Flexibilität: Kampagnen nur durch Konfiguration aufsetzen, Schnittstellen in 8 Stunden. Kampagnenspezifischer Code wird aus einem UML-Modell generiert. Die Ablaufsteuerung basiert auf Regeln (Geschäftsregel). Die Risiken dokumentiert das Beispiel offen, etwa einen überladenen Receiver-Baustein mit schlechter Kohäsion (S. 377–406).
Werkzeuge
Für kleine und mittlere Systeme empfiehlt Starke ein Wiki oder Klartext wie Markdown und AsciiDoc. Diagramme entstehen mit einfachen Grafikwerkzeugen oder textuell mit PlantUML. Bei jedem Release wird ein PDF erzeugt und zusammen mit dem Code versioniert (S. 181). docToolchain erzeugt aus AsciiDoc HTML, PDF oder Confluence (S. 408).
Aktueller Stand
Version 9.0 erschien im Juli 2025. Abschnitt 10 (Qualitätsanforderungen) ist jetzt in Überblick (10.1) und Details (10.2) gegliedert. Die Vorlage gibt es in 12 Sprachen und vielen Formaten (u. a. Markdown, AsciiDoc, docx), frei und quelloffen (Quelle - Recherche - Softwarearchitektur heute 2026).
Dieses Wiki folgt genau Starkes Rat: Klartext (Markdown), versioniert mit Git, eine generierte HTML-Seite als Ausgabe (tools/build_site.py).
Verwandt
- Softwarearchitektur – was dokumentiert wird
- Softwarequalität – Abschnitte 1.2 und 10
- Architekturbewertung – Bewertung setzt Dokumentation voraus
- Gernot Starke – Mitbegründer von arc42
- aim42 – das Schwesterprojekt für Verbesserung
- LLM Wiki – dieses Wiki als Klartext-Dokumentation