Von verstreutem Architekturwissen zu Views, Entscheidungen und kommunizierbarer Dokumentation.
Eine lebende Architekturdokumentation mit Views, Rationale, Kommunikationsplan und Pflegeverantwortung.
Du kannst entscheiden, welche Architekturinformationen verbindlich dokumentiert, gepflegt und kommuniziert werden.
Dokumentationsstruktur veröffentlichen, Pflegeowner setzen und Review-Rhythmus etablieren.
Welchen Systemkontext, welche Randbedingungen und Entscheidungen muss die Architektur vermitteln?
arc42 liefert eine robuste Struktur für Ziele, Kontext, Bausteine, Laufzeit, Entscheidungen und Risiken.
Die Struktur wird anschließend mit geeigneten Architekturdiagrammen konkretisiert.
Welche Diagramme helfen den jeweiligen Zielgruppen, die Softwarearchitektur zu verstehen?
Das C4 Model macht System, Container und Components auf unterschiedlichen Abstraktionsebenen verständlich.
Die Diagramme werden danach um stakeholderrelevante Sichten ergänzt.
Welche Sichten dienen diesen Stakeholdern, und welche Informationen müssen über die einzelnen Sichten hinaus dokumentiert werden?
Views and Beyond hilft, Architekturinformationen aus Sicht verschiedener Stakeholder und Qualitätsfragen zu organisieren.
Die Sichten brauchen anschließend eine passende Kommunikationsstrategie.
Welche wesentlichen Systeminformationen müssen diese Empfänger verstehen, prüfen oder weitertragen?
Der Architecture Communication Canvas verbindet Publikum, Botschaft, Artefakt und Kommunikationsziel.
Die Kommunikationsplanung macht aus Dokumentation ein nutzbares, gepflegtes Arbeitsmittel.
Die Artefakte bleiben zugeklappt, bis du sie wirklich brauchst.
Bereite Entscheidung, Quellenbelege und nächste Prüfung vor.
# arc42: Arbeitsvorlage
## Fragestellung
Noch zu klären
## Gewünschtes Ergebnis
Noch zu klären
## Rahmen
Methode durchführen
Zeit: Siehe Zeitrahmen im Katalog; keine allgemeine Dauer.
Diese Vorlage während der Arbeit auf Papier oder in einem eigenen Dokument ausfüllen.
## Vorbereitung für diesen Umfang
### Methodische Grundausstattung
- **Materialien:** Gemeinsame Arbeitsfläche, Quellenbelege und eine abgestimmte Entscheidungsfrage.
- **Rollen:** Architektur, Entwicklung, Betrieb, Fachbereiche, Entscheidungsverantwortung.
- **Vorab-Infos:** Sammle vorhandene Daten, Beispiele, Rahmenbedingungen und relevante Perspektiven.
- **Gesamter Zeitbedarf:** Mehrere fokussierte Termine; Umfang nach Komplexität und Beleglage bestimmen.
- **Setup:** Das Team füllt die relevanten Kapitel von Kontext über Bausteine bis zu Laufzeit, Deployment und Risiken. Dabei werden Inhalte knapp, referenzierbar und anschlussfähig gehalten, damit Dokumentation und Gespräche dieselbe Basis haben. Am Ende entsteht ein durchgehendes Architekturprofil, das Pflege und Übergaben erleichtert.
### Für die Arbeitsschritte bereitstellen
#### Umfang: System und Dokumentationsbedarf festlegen
- Systemgrenze, Zielgruppen, bestehende Architekturdokumente
#### Ziele: Ziele, Constraints und Kontext dokumentieren
- Requirements, Randbedingungen, externe Systeme
#### Sichten: Lösungsstrategie und Sichten entwickeln
- Qualitätsziele, vorhandene Architektur, kritische Szenarien
#### Pflege: Qualität, Entscheidungen und Pflege sichern
- Qualitätsszenarien, Risiken, technische Schulden, Teamverantwortung
## arc42-Architekturdokumentation
### Einführung und Ziele
Stakeholder, Anforderungen und wichtigste Qualitätsziele festhalten.
...
### Randbedingungen
Technische, organisatorische und regulatorische Vorgaben benennen.
...
### Kontext und Abgrenzung
Systemgrenze, externe Partner und Schnittstellen erklären.
...
### Lösungsstrategie
Leitende Ansätze und wichtige Architekturentscheidungen begründen.
...
### Bausteinsicht
Relevante Bausteine und ihre Verantwortung zeigen.
...
### Laufzeitsicht
Kritische Szenarien und Interaktionen beschreiben.
...
### Verteilungssicht
Infrastruktur und Zuordnung von Softwarebausteinen abbilden.
...
### Querschnittliche Konzepte
Wiederkehrende Konzepte und Regeln dokumentieren.
...
### Architekturentscheidungen
Wichtige Entscheidungen mit Status und Begründung verknüpfen.
...
### Qualitätsanforderungen
Qualitätsszenarien messbar formulieren.
...
### Risiken und technische Schulden
Bekannte Risiken samt Wirkung und Umgang festhalten.
...
### Glossar
Domänenbegriffe konsistent definieren.
...
Das leere Dokument enthält ausschließlich Abschnittsimpulse.
[arc42 at a glance](https://arc42.org/overview/)
## Umfang: System und Dokumentationsbedarf festlegen
Erwartetes Artefakt: Schlanker Dokumentationsplan
Schlanker Dokumentationsplan
Eintrag:
...
- [ ] Ist jedes Kapitel für Stakeholder oder Entwicklung nützlich?
## Ziele: Ziele, Constraints und Kontext dokumentieren
Erwartetes Artefakt: Abschnitte 1 bis 3 mit Belegen
Abschnitte 1 bis 3 mit Belegen
Eintrag:
...
- [ ] Sind Qualitätsziele überprüfbar und Schnittstellen benannt?
## Sichten: Lösungsstrategie und Sichten entwickeln
Erwartetes Artefakt: Architekturbeschreibung und relevante Sichten
Architekturbeschreibung und relevante Sichten
Eintrag:
...
- [ ] Beantwortet jede Sicht eine konkrete Qualitäts- oder Strukturfrage?
## Pflege: Qualität, Entscheidungen und Pflege sichern
Erwartetes Artefakt: Lebende arc42-Dokumentation
Lebende arc42-Dokumentation
Eintrag:
...
- [ ] Kann ein Leser erkennen, was aktuell, offen oder überholt ist?
## Offene Fragen und nächste Schritte
...
Methodenanleitung: https://methodatlas.meierhoff-systems.de/de/methods/arc42/run-sheet
Bereite Entscheidung, Quellenbelege und nächste Prüfung vor.
# C4 Model: Arbeitsvorlage
## Fragestellung
Noch zu klären
## Gewünschtes Ergebnis
Noch zu klären
## Rahmen
Methode durchführen
Zeit: Siehe Zeitrahmen im Katalog; keine allgemeine Dauer.
Diese Vorlage während der Arbeit auf Papier oder in einem eigenen Dokument ausfüllen.
## Vorbereitung für diesen Umfang
### Methodische Grundausstattung
- **Materialien:** Gemeinsame Arbeitsfläche, Quellenbelege und eine abgestimmte Entscheidungsfrage.
- **Rollen:** Architektur oder technische Leitung, Entwicklung, Product-/Fachvertretung.
- **Vorab-Infos:** Sammle vorhandene Daten, Beispiele, Rahmenbedingungen und relevante Perspektiven.
- **Gesamter Zeitbedarf:** 60–120 Min. für ein erstes Modell; Details und Review hängen vom Systemumfang ab.
- **Setup:** Zuerst wird der Systemkontext mit Menschen, Nachbarsystemen und Grenzen beschrieben. Danach werden Container, Components und bei Bedarf Code-Sicht ergänzend dargestellt. So bleibt die Architektur auf jeder Ebene anschlussfähig, ohne in einem einzigen Diagramm zu viel zu überladen.
### Für die Arbeitsschritte bereitstellen
#### Frage: System, Zielgruppe und Frage wählen
- Systemgrenze, Gesprächsanlass, Zielgruppe
#### Kontext: System Context darstellen
- Nutzer, Nachbarsysteme und belegte Beziehungen
#### Container: Container-Sicht ergänzen
- Context-Sicht, ausführbare Deployables und Datenspeicher
#### Details: Nur benötigte Zoomstufen pflegen
- Offene Architekturfrage, Diagrammkonventionen und Owner
## C4-Sichten
### System Context
System, Menschen und Nachbarsysteme mit Beziehungen darstellen.
...
### Container
Anwendungen, Services und Datenspeicher der Systemgrenze zeigen.
...
### Component
Innere Bausteine nur zur Klärung einer konkreten Frage zerlegen.
...
### Code
Code-Ebene nur bei relevantem Detailbedarf nutzen.
...
### Supporting diagrams
Dynamic, deployment oder landscape ergänzen, wenn die Kommunikation es verlangt.
...
Das leere Dokument enthält ausschließlich Abschnittsimpulse.
[C4 model: Diagrams](https://c4model.com/diagrams)
## Frage: System, Zielgruppe und Frage wählen
Erwartetes Artefakt: Diagrammauftrag
Diagrammauftrag
Eintrag:
...
- [ ] Ist die Frage mit einer Architekturansicht beantwortbar?
## Kontext: System Context darstellen
Erwartetes Artefakt: System-Context-Diagramm
System-Context-Diagramm
Eintrag:
...
- [ ] Sind externe Abhängigkeiten und Systemgrenze klar?
## Container: Container-Sicht ergänzen
Erwartetes Artefakt: Container-Diagramm
Container-Diagramm
Eintrag:
...
- [ ] Sind Container deploybare oder ausführbare Einheiten?
## Details: Nur benötigte Zoomstufen pflegen
Erwartetes Artefakt: Kohärenter Satz C4-Sichten
Kohärenter Satz C4-Sichten
Eintrag:
...
- [ ] Sind Begriffe, Richtung und Detailgrad für Leser verständlich?
## Offene Fragen und nächste Schritte
...
Methodenanleitung: https://methodatlas.meierhoff-systems.de/de/methods/c4-model/run-sheet
Plane die Arbeit an einem ADR vom Kontext über die Abwägung bis zum vereinbarten Review.
# Architecture Decision Record: Arbeitsvorlage
## Fragestellung
Noch zu klären
## Gewünschtes Ergebnis
Noch zu klären
## Rahmen
Einen ADR vorbereiten und abstimmen
Zeit: Entwurf und Review getrennt vereinbaren
Diese Vorlage während der Arbeit auf Papier oder in einem eigenen Dokument ausfüllen.
## Vorbereitung für diesen Umfang
### Methodische Grundausstattung
- **Materialien:** Kurze Textvorlage, relevanter Architekturkontext, Quellen zu betrachteten Optionen und eine versionierte, für Beteiligte auffindbare Ablage.
- **Rollen:** Eine verantwortliche Person verfasst den Entwurf. Betroffene Engineering-, Architektur-, Produkt- oder Betriebsrollen prüfen relevante Folgen. Die vereinbarte Entscheidungsverantwortung nimmt die Entscheidung ausdrücklich an.
- **Vorab-Infos:** Entscheidungsfrage, bestehende Architektur, betroffene Qualitätsanforderungen und bekannte Einschränkungen sammeln. Frühere einschlägige ADRs und Quellen verlinken.
- **Gesamter Zeitbedarf:** 15 bis 45 Minuten für einen fokussierten Entwurf als Orientierung. Untersuchung, Diskussion und Review kommen hinzu und können asynchron erfolgen. Einen passenden Rückmeldetermin gemeinsam vereinbaren.
- **Setup:** Stabile Kennung und kurzen Titel vergeben, Status vorgeschlagen setzen und die Notiz in der gemeinsamen Ablage anlegen. Entscheidungs- und Reviewweg mit den Beteiligten klären.
### Für die Arbeitsschritte bereitstellen
#### Frame: Entscheidung und Kontext klären
- Architekturfrage und bestehender Systemkontext
#### Compare: Relevante Optionen abwägen
- Entscheidungskontext und realistische Optionen
#### Decide: Entscheidung prüfen und festhalten
- Entwurf, Abwägung und betroffene Perspektiven
#### Maintain: Folgen verfolgen und Historie erhalten
- ADR mit geklärtem Status und Folgeaufgaben
## Aufbau eines ADR
### Kennung, Titel und Status
Stabile Kennung, Entscheidungsfrage, Datum, Beteiligte, Verantwortung und aktuellen Status notieren.
...
### Kontext und Entscheidungsfaktoren
Warum ist diese Entscheidung nötig? Welche Anforderungen und Einschränkungen bestimmen sie?
...
### Betrachtete Optionen
Relevante Optionen, entscheidende Unterschiede, Quellen und Unsicherheiten knapp vergleichen.
...
### Entscheidung und Begründung
Die gewählte Option und ihre entscheidenden Gründe festhalten. Im Entwurf den Vorschlagsstatus kenntlich machen.
...
### Konsequenzen und Folgeaufgaben
Relevante positive und nachteilige Folgen, Unsicherheiten und konkrete Folgeaufgaben beschreiben.
...
### Review, Statuswechsel und Verknüpfungen
Reviewweg, ausdrückliche Entscheidung und Datum dokumentieren. Quellen sowie Vorgänger oder Nachfolger verlinken.
...
Mit Status vorgeschlagen beginnen. Annahme ausdrücklich dokumentieren. Eine geänderte Entscheidung als neuen ADR verknüpfen und die ursprüngliche Begründung erhalten.
[Nach Michael Nygard, ergänzt um Optionen und Review](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
## Frame: Entscheidung und Kontext klären
Erwartetes Artefakt: Entscheidungskontext
Frage · Bedeutung · Rahmen · Verantwortung
Eintrag:
...
- [ ] Kann eine spätere Person die Ausgangslage verstehen?
## Compare: Relevante Optionen abwägen
Erwartetes Artefakt: Nachvollziehbare Abwägung
Option · relevante Wirkung · Unsicherheit · Quelle
Eintrag:
...
- [ ] Werden reale Optionen am selben Kontext betrachtet?
## Decide: Entscheidung prüfen und festhalten
Erwartetes Artefakt: ADR mit geklärtem Status
Wahl · Gründe · Folgen · Status · Datum
Eintrag:
...
- [ ] Ist die Entscheidung ausdrücklich bestätigt und dokumentiert?
- [ ] Sind relevante Folgen und offene Aufgaben verständlich?
## Maintain: Folgen verfolgen und Historie erhalten
Erwartetes Artefakt: Verknüpfte Entscheidungshistorie
Folgeaufgabe · Anlass · Vorgänger · Nachfolger
Eintrag:
...
- [ ] Sind die frühere Begründung und der aktuelle Status auffindbar?
## Offene Fragen und nächste Schritte
...
Methodenanleitung: https://methodatlas.meierhoff-systems.de/de/methods/adr/run-sheet