Stefan Zörner
Softwarearchitekturen dokumentieren und kommunizieren
Entwürfe, Entscheidungen und Lösungen nachvollziehbar und wirkungsvoll festhalten
Inhalt
6
Geleitwort zur.1..Auflage
12
Überblick: Dokumentationsmittel im Buch
14
1 Warum Softwarearchitekturen dokumentieren?
16
1.1 Montagmorgen
16
1.1.1 Fragen über Fragen
16
1.1.2 Wer fragt, bekommt Antworten …
17
1.2 Voll unagil?
19
1.2.1 Agil vorgehen
20
1.2.2 Funktionierende Software vor umfassender Dokumentation
21
1.2.3 Dokumentation unterstützt Kommunikation
22
1.3 Wirkungsvolle Architekturdokumentation
22
1.3.1 Ziel.1: Architekturarbeit unterstützen
23
1.3.2 Ziel.2: Architektur nachvollziehbar und bewertbar machen
23
1.3.3 Ziel.3: Umsetzung und Weiterentwicklung leiten
24
1.3.4 Fremdwort Do|ku|men|ta|tion […zion] [lat.]
24
1.4 Mission Statement für dieses Buch
25
1.5 Über dieses Buch
26
1.5.1 Für wen ich dieses Buch geschrieben habe
26
1.5.2 Wie dieses Buch aufgebaut ist
27
1.5.3 Wem ich Dankeschön sagen möchte
31
2 Was Softwarearchitektur ist und worauf sie aufbaut
32
2.1 Softwarearchitektur-Freischwimmer
32
2.1.1 Was ist Softwarearchitektur?
32
2.1.2 Wie entsteht Softwarearchitektur?
33
2.1.3 Wer oder was ist ein Softwarearchitekt?
36
2.1.4 Ein Architekturüberblick auf n Seiten, n < 30
38
2.2 Die Zielsetzung vermitteln
38
2.2.1 Jetzt kommt ein Karton!
38
2.2.2 Virtueller Produktkarton (Dokumentationsmittel)
39
2.2.3 Fallbeispiel: Schach-Engine „DokChess“
40
2.2.4 Tipps zum Erstellen von Produktkartons
41
2.2.5 Fallbeispiel: Schachplattform „immer-nur-schach.de“
42
2.3 Den Kontext abgrenzen
43
2.3.1 Systemkontext (Dokumentationsmittel)
44
2.3.2 Fallbeispiel: Systemkontext „immer-nur-schach.de“
45
2.3.3 Tipps zur Erstellung des Systemkontextes
46
2.4 Im Rahmen bleiben
51
2.4.1 Warum Randbedingungen festhalten?
51
2.4.2 Randbedingungen (Dokumentationsmittel)
53
2.4.3 Fallbeispiel: Randbedingungen „immer-nur-schach.de“
53
2.4.4 Tipps zum Festhalten von Randbedingungen
54
2.5 Geforderte Qualitätsmerkmale
56
2.5.1 Was sind Qualitätsmerkmale?
57
2.5.2 Qualitätsziele (Dokumentationsmittel)
58
2.5.3 Fallbeispiel: Qualitätsziele „immer-nur-schach.de“
59
2.5.4 Fallbeispiel: Qualitätsziele „DokChess“
59
2.5.5 Qualitätsmerkmale genauer beschreiben
61
2.5.6 Qualitätsszenarien (Dokumentationsmittel)
62
2.5.7 Fallbeispiel: Qualitätsszenarien „immer-nur-schach.de“
63
2.5.8 Tipps zum Festhalten von Qualitätsszenarien
65
2.6 Weitere Einflüsse und Hilfsmittel
68
2.6.1 Stakeholder
68
2.6.2 Persona (Dokumentationsmittel)
69
2.6.3 Fallbeispiel: Persona „immer-nur-schach.de“
70
2.6.4 Risiken
72
2.6.5 Technische Risiken (Dokumentationsmittel)
73
2.6.6 Fallbeispiel: Technische Risiken „DokChess“
73
2.6.7 Glossar (Dokumentationsmittel)
74
3 Entscheidungen treffen und festhalten
76
3.1 Historisch gewachsen?
76
3.2 Architekturentscheidungen
77
3.2.1 Architekturentscheidung (Dokumentationsmittel)
77
3.2.2 Fallbeispiel: Spannende Fragen „DokChess“
79
3.2.3 Tipps zur Formulierung von Fragestellungen
79
3.2.4 Fallbeispiel: Fragestellungen „immer-nur-schach.de“
81
3.3 Einflussfaktoren auf Entscheidungen
85
3.3.1 Den Überblick behalten
85
3.3.2 Kreuztabellen
86
3.3.3 Fallbeispiel: Einflüsse „immer-nur-schach.de“
87
3.3.4 Tipps zur Anfertigung von Kreuztabellen
88
3.4 Kompakte Darstellung der.Lösungsstrategie
89
3.4.1 Softwarearchitektur auf einem Bierdeckel?
90
3.4.2 Lösungsstrategie (Dokumentationsmittel)
90
3.4.3 Fallbeispiel: Lösungsstrategie „DokChess“
92
3.4.4 Als Ergänzung: ein Überblicksbild
93
3.4.5 Eine Architekturbewertung auf dem Bierdeckel
93
4 Plädoyer für eine feste Gliederung
94
4.1 Der jüngste Spieler fängt an!
94
4.2 Vorteile einer festen Struktur
95
4.3 arc42 – Vorschlag für eine Gliederung
97
4.3.1 Was ist arc42?
97
4.3.2 Die Struktur der arc42-Vorlage
98
4.3.3 Wo funktioniert arc42 besonders gut?
100
4.3.4 arc42 in diesem Buch
101
4.4 Alternativen zu arc42
102
4.4.1 Standards zur Architekturbeschreibung
102
4.4.2 Vorgehensmodelle
103
4.4.3 Architektur-Frameworks
105
4.4.4 Fachliteratur als Inspiration?
106
5 Sichten auf Softwarearchitektur
110
5.1 Strukturen entwerfen und festhalten
110
5.1.1 Was ist was? Band.127: Unser Softwaresystem
110
5.1.2 Schritte der Zerlegung dokumentieren
111
5.1.3 Bausteinsicht (Dokumentationsmittel)
112
5.1.4 Fallbeispiel: Bausteinsicht „DokChess“ (Ausschnitt)
113
5.1.5 Komponenten: Babylonische Sprachverwirrung 2.0
114
5.1.6 Tipps zur Erstellung der Bausteinsicht
115
5.1.7 Interaktionspunkte beschreiben
120
5.1.8 Schnittstellenbeschreibung (Dokumentationsmittel)
123
5.1.9 Fallbeispiel: Schnittstellen der Eröffnung in „DokChess“
125
5.2 Verschiedene Blickwinkel
128
5.2.1 Hat Mozart modelliert?
128
5.2.2 Fachliche Zerlegung vs. technische Zerlegung
130
5.2.3 Fallbeispiel: Bausteinsicht „immer-nur-schach.de“
132
5.3 Verhalten und Abläufe beschreiben
135
5.3.1 Abläufe in Entwurf und Dokumentation
135
5.3.2 Darstellungen für Abläufe
135
5.3.3 Laufzeitsicht (Dokumentationsmittel)
138
5.3.4 Fallbeispiel: Ablauf in DokChess
139
5.3.5 Fallbeispiel: Zustandsautomat XBoard (DokChess)
139
5.4 Die Dinge zum Einsatz bringen
140
5.4.1 Betriebsaspekte in der Architekturdokumentation
141
5.4.2 Darstellungen für Verteilung
142
5.4.3 Verteilungssicht (Dokumentationsmittel)
144
5.4.4 Fallbeispiel: „immer-nur-schach.de“
146
5.5 Alternative Vorschläge für Sichten
147
5.6 Muster kommunizieren
150
5.6.1 Muster in der Softwareentwicklung
150
5.6.2 Wann sollte man Muster dokumentieren (und wo)?
151
5.6.3 Einsatz von Mustern dokumentieren
151
5.6.4 Fallbeispiel: DokChess
153
6 Übergreifende Konzepte
154
6.1 Warum übergreifende Themen?
154
6.2 Themen und Lösungsoptionen
155
6.2.1 Mögliche Themen für übergreifende Konzepte
155
6.2.2 Typische Lösungsoptionen
157
6.3 Themenauswahl
159
6.3.1 Wie wählt man Themen für die Dokumentation aus?
160
6.3.2 Fallbeispiel: Übergreifende Themen „DokChess“
161
6.4 Eine Gliederungstechnik für Konzepte
163
6.4.1 Werkzeug: Warum? Was? Wie? Wohin noch?
163
6.4.2 Gliederung für ein Konzept
165
6.4.3 Informeller Text für den Architekturüberblick
167
6.5 Tipps zur Erstellung übergreifender Konzepte
168
7 Werkzeuge zur Dokumentation
172
7.1 Notationen passgenau wählen
172
7.2 Toolparade zur Architekturdokumentation
177
7.2.1 Erstellung und Pflege
177
7.2.2 Verwaltung von Inhalten
183
7.2.3 Kommunikation von Lösungen
185
7.3 Repository: UML vs. Wiki
187
7.3.1 Steht alles im Wiki?
188
7.3.2 Steht alles im UML-Tool?
191
7.3.3 UML-Tool + Wiki == Traumpaar?
194
7.4 Wie auswählen?
195
8 Lightfäden für das Vorgehen zur Dokumentation
198
8.1 Während der Entwicklung dokumentieren
198
8.1.1 Zielgruppen Ihrer Dokumentation
198
8.1.2 Dokumentationsmittel und Dokumente
201
8.1.3 Womit anfangen?
204
8.1.4 Während der Arbeit: Kommunizieren und Pflegen
205
8.2 Der Softwaredetektiv: Bestehendes Dokumentieren
207
8.2.1 Auslöser für Dokumentationsbedarf
207
8.2.2 Mögliche Szenarien und Ziele des Dokumentierens im Nachhinein
208
8.2.3 Sherlock Holmes vs. Die drei ???
209
8.2.4 Informationsquellen identifizieren
210
8.2.5 Dokumentationsmittel unter der Lupe
211
8.2.6 Exkurs: Werkzeuge zur Rekonstruktion
216
8.3 Variationen von „Ein System“
221
8.3.1 Dokumentation von Systemlandschaften
221
8.3.2 Dokumentation von Frameworks und Blue Prints
223
9 Architekturüberblick DokChess
226
9.1 Einführung und Ziele
227
9.1.1 Aufgabenstellung
227
9.1.2 Qualitätsziele
227
9.1.3 Stakeholder
228
9.2 Randbedingungen
231
9.2.1 Technische Randbedingungen
231
9.2.2 Organisatorische Randbedingungen
231
9.2.3 Konventionen
232
9.3 Kontextabgrenzung
233
9.3.1 Fachlicher Kontext
233
9.3.2 Technischer- oder Verteilungskontext
234
9.4 Lösungsstrategie
235
9.4.1 Aufbau von DokChess
236
9.4.2 Spielstrategie
237
9.4.3 Die Anbindung
237
9.5 Bausteinsicht
238
9.5.1 Ebene.1
238
9.5.2 XBoard-Protokoll (Blackbox)
239
9.5.3 Spielregeln (Blackbox)
240
9.5.4 Engine (Blackbox)
241
9.5.5 Eröffnung (Blackbox)
242
9.5.6 Ebene.2: Engine (Whitebox)
244
9.5.7 Zugsuche (Blackbox)
244
9.5.8 Stellungsbewertung (Blackbox)
246
9.6 Laufzeitsicht
247
9.6.1 Zugermittlung Walkthrough
247
9.7 Verteilungssicht
248
9.7.1 Infrastruktur Windows
248
9.8 Konzepte
250
9.8.1 Abhängigkeiten zwischen Modulen
250
9.8.2 Schach-Domänenmodell
250
9.8.3 Benutzungsoberfläche
252
9.8.4 Plausibilisierung und Validierung
253
9.8.5 Ausnahme- und Fehlerbehandlung
254
9.8.6 Logging, Protokollierung, Tracing
254
9.8.7 Testbarkeit
255
9.9 Entwurfsentscheidungen
257
9.9.1 Wie kommuniziert die Engine mit der Außenwelt?
257
9.9.2 Sind Stellungsobjekte veränderlich oder nicht?
259
9.10 Qualitätsszenarien
262
9.10.1 Qualitätsbaum
262
9.10.2 Bewertungsszenarien
263
9.11 Risiken
264
9.11.1 Risiko: Anbindung an das Frontend
264
9.11.2 Risiko: Aufwand der Implementierung
264
9.11.3 Risiko: Erreichen der Spielstärke
265
9.12 Glossar
266
10 Stolpersteine der Architekturdokumentation
268
10.1 Probleme
268
10.2 Fiese Fallen …
270
10.3 … und wie man sie umgeht oder entschärft
272
10.4 Reviews von Architekturdokumentation
273
Glossar
280
Literaturverzeichnis
284
Stichwortverzeichnis
288
© 2009-2024 ciando GmbH