Softwarearchitekturen dokumentieren und kommunizieren

Inhalt

Geleitwort zur.1..Auflage

Überblick: Dokumentationsmittel im Buch

1 Warum Software­architekturen dokumentieren?

1.1 Montagmorgen

1.1.1 Fragen über Fragen

1.1.2 Wer fragt, bekommt Antworten …

1.2 Voll unagil?

1.2.1 Agil vorgehen

1.2.2 Funktionierende Software vor umfassender Dokumentation

1.2.3 Dokumentation unterstützt Kommunikation

1.3 Wirkungsvolle Architektur­dokumentation

1.3.1 Ziel.1: Architekturarbeit unterstützen

1.3.2 Ziel.2: Architektur nachvollziehbar und bewertbar machen

1.3.3 Ziel.3: Umsetzung und Weiterentwicklung leiten

1.3.4 Fremdwort Do|ku|men|ta|tion […zion] [lat.]

1.4 Mission Statement für dieses Buch

1.5 Über dieses Buch

1.5.1 Für wen ich dieses Buch geschrieben habe

1.5.2 Wie dieses Buch aufgebaut ist

1.5.3 Wem ich Dankeschön sagen möchte

2 Was Software­architektur ist und worauf sie aufbaut

2.1 Softwarearchitektur-Freischwimmer

2.1.1 Was ist Softwarearchitektur?

2.1.2 Wie entsteht Softwarearchitektur?

2.1.3 Wer oder was ist ein Softwarearchitekt?

2.1.4 Ein Architekturüberblick auf n Seiten, n < 30

2.2 Die Zielsetzung vermitteln

2.2.1 Jetzt kommt ein Karton!

2.2.2 Virtueller Produktkarton (Dokumentationsmittel)

2.2.3 Fallbeispiel: Schach-Engine „DokChess“

2.2.4 Tipps zum Erstellen von Produktkartons

2.2.5 Fallbeispiel: Schachplattform „immer-nur-schach.de“

2.3 Den Kontext abgrenzen

2.3.1 Systemkontext (Dokumentationsmittel)

2.3.2 Fallbeispiel: Systemkontext „immer-nur-schach.de“

2.3.3 Tipps zur Erstellung des Systemkontextes

2.4 Im Rahmen bleiben

2.4.1 Warum Randbedingungen festhalten?

2.4.2 Randbedingungen (Dokumentationsmittel)

2.4.3 Fallbeispiel: Randbedingungen „immer-nur-schach.de“

2.4.4 Tipps zum Festhalten von Randbedingungen

2.5 Geforderte Qualitätsmerkmale

2.5.1 Was sind Qualitätsmerkmale?

2.5.2 Qualitätsziele (Dokumentationsmittel)

2.5.3 Fallbeispiel: Qualitätsziele „immer-nur-schach.de“

2.5.4 Fallbeispiel: Qualitätsziele „DokChess“

2.5.5 Qualitätsmerkmale genauer beschreiben

2.5.6 Qualitätsszenarien (Dokumentationsmittel)

2.5.7 Fallbeispiel: Qualitätsszenarien „immer-nur-schach.de“

2.5.8 Tipps zum Festhalten von Qualitätsszenarien

2.6 Weitere Einflüsse und Hilfsmittel

2.6.1 Stakeholder

2.6.2 Persona (Dokumentationsmittel)

2.6.3 Fallbeispiel: Persona „immer-nur-schach.de“

2.6.4 Risiken

2.6.5 Technische Risiken (Dokumentationsmittel)

2.6.6 Fallbeispiel: Technische Risiken „DokChess“

2.6.7 Glossar (Dokumentationsmittel)

3 Entscheidungen treffen und festhalten

3.1 Historisch gewachsen?

3.2 Architekturentscheidungen

3.2.1 Architekturentscheidung (Dokumentationsmittel)

3.2.2 Fallbeispiel: Spannende Fragen „DokChess“

3.2.3 Tipps zur Formulierung von Fragestellungen

3.2.4 Fallbeispiel: Fragestellungen „immer-nur-schach.de“

3.3 Einflussfaktoren auf Entscheidungen

3.3.1 Den Überblick behalten

3.3.2 Kreuztabellen

3.3.3 Fallbeispiel: Einflüsse „immer-nur-schach.de“

3.3.4 Tipps zur Anfertigung von Kreuztabellen

3.4 Kompakte Darstellung der.Lösungsstrategie

3.4.1 Softwarearchitektur auf einem Bierdeckel?

3.4.2 Lösungsstrategie (Dokumentationsmittel)

3.4.3 Fallbeispiel: Lösungsstrategie „DokChess“

3.4.4 Als Ergänzung: ein Überblicksbild

3.4.5 Eine Architekturbewertung auf dem Bierdeckel

4 Plädoyer für eine feste Gliederung

4.1 Der jüngste Spieler fängt an!

4.2 Vorteile einer festen Struktur

4.3 arc42 – Vorschlag für eine Gliederung

4.3.1 Was ist arc42?

4.3.2 Die Struktur der arc42-Vorlage

4.3.3 Wo funktioniert arc42 besonders gut?

4.3.4 arc42 in diesem Buch

4.4 Alternativen zu arc42

4.4.1 Standards zur Architekturbeschreibung

4.4.2 Vorgehensmodelle

4.4.3 Architektur-Frameworks

4.4.4 Fachliteratur als Inspiration?

5 Sichten auf Softwarearchitektur

5.1 Strukturen entwerfen und festhalten

5.1.1 Was ist was? Band.127: Unser Softwaresystem

5.1.2 Schritte der Zerlegung dokumentieren

5.1.3 Bausteinsicht (Dokumentationsmittel)

5.1.4 Fallbeispiel: Bausteinsicht „DokChess“ (Ausschnitt)

5.1.5 Komponenten: Babylonische Sprachverwirrung 2.0

5.1.6 Tipps zur Erstellung der Bausteinsicht

5.1.7 Interaktionspunkte beschreiben

5.1.8 Schnittstellenbeschreibung (Dokumentationsmittel)

5.1.9 Fallbeispiel: Schnittstellen der Eröffnung in „DokChess“

5.2 Verschiedene Blickwinkel

5.2.1 Hat Mozart modelliert?

5.2.2 Fachliche Zerlegung vs. technische Zerlegung

5.2.3 Fallbeispiel: Bausteinsicht „immer-nur-schach.de“

5.3 Verhalten und Abläufe beschreiben

5.3.1 Abläufe in Entwurf und Dokumentation

5.3.2 Darstellungen für Abläufe

5.3.3 Laufzeitsicht (Dokumentationsmittel)

5.3.4 Fallbeispiel: Ablauf in DokChess

5.3.5 Fallbeispiel: Zustandsautomat XBoard (DokChess)

5.4 Die Dinge zum Einsatz bringen

5.4.1 Betriebsaspekte in der Architekturdokumentation

5.4.2 Darstellungen für Verteilung

5.4.3 Verteilungssicht (Dokumentationsmittel)

5.4.4 Fallbeispiel: „immer-nur-schach.de“

5.5 Alternative Vorschläge für Sichten

5.6 Muster kommunizieren

5.6.1 Muster in der Softwareentwicklung

5.6.2 Wann sollte man Muster dokumentieren (und wo)?

5.6.3 Einsatz von Mustern dokumentieren

5.6.4 Fallbeispiel: DokChess

6 Übergreifende Konzepte

6.1 Warum übergreifende Themen?

6.2 Themen und Lösungsoptionen

6.2.1 Mögliche Themen für übergreifende Konzepte

6.2.2 Typische Lösungsoptionen

6.3 Themenauswahl

6.3.1 Wie wählt man Themen für die Dokumentation aus?

6.3.2 Fallbeispiel: Übergreifende Themen „DokChess“

6.4 Eine Gliederungstechnik für Konzepte

6.4.1 Werkzeug: Warum? Was? Wie? Wohin noch?

6.4.2 Gliederung für ein Konzept

6.4.3 Informeller Text für den Architekturüberblick

6.5 Tipps zur Erstellung übergreifender Konzepte

7 Werkzeuge zur Dokumentation

7.1 Notationen passgenau wählen

7.2 Toolparade zur Architekturdokumentation

7.2.1 Erstellung und Pflege

7.2.2 Verwaltung von Inhalten

7.2.3 Kommunikation von Lösungen

7.3 Repository: UML vs. Wiki

7.3.1 Steht alles im Wiki?

7.3.2 Steht alles im UML-Tool?

7.3.3 UML-Tool + Wiki == Traumpaar?

7.4 Wie auswählen?

8 Lightfäden für das Vorgehen zur Dokumentation

8.1 Während der Entwicklung dokumentieren

8.1.1 Zielgruppen Ihrer Dokumentation

8.1.2 Dokumentationsmittel und Dokumente

8.1.3 Womit anfangen?

8.1.4 Während der Arbeit: Kommunizieren und Pflegen

8.2 Der Softwaredetektiv: Bestehendes Dokumentieren

8.2.1 Auslöser für Dokumentationsbedarf

8.2.2 Mögliche Szenarien und Ziele des Dokumentierens im Nachhinein

8.2.3 Sherlock Holmes vs. Die drei ???

8.2.4 Informationsquellen identifizieren

8.2.5 Dokumentationsmittel unter der Lupe

8.2.6 Exkurs: Werkzeuge zur Rekonstruktion

8.3 Variationen von „Ein System“

8.3.1 Dokumentation von Systemlandschaften

8.3.2 Dokumentation von Frameworks und Blue Prints

9 Architekturüberblick DokChess

9.1 Einführung und Ziele

9.1.1 Aufgabenstellung

9.1.2 Qualitätsziele

9.1.3 Stakeholder

9.2 Randbedingungen

9.2.1 Technische Randbedingungen

9.2.2 Organisatorische Randbedingungen

9.2.3 Konventionen

9.3 Kontextabgrenzung

9.3.1 Fachlicher Kontext

9.3.2 Technischer- oder Verteilungskontext

9.4 Lösungsstrategie

9.4.1 Aufbau von DokChess

9.4.2 Spielstrategie

9.4.3 Die Anbindung

9.5 Bausteinsicht

9.5.1 Ebene.1

9.5.2 XBoard-Protokoll (Blackbox)

9.5.3 Spielregeln (Blackbox)

9.5.4 Engine (Blackbox)

9.5.5 Eröffnung (Blackbox)

9.5.6 Ebene.2: Engine (Whitebox)

9.5.7 Zugsuche (Blackbox)

9.5.8 Stellungsbewertung (Blackbox)

9.6 Laufzeitsicht

9.6.1 Zugermittlung Walkthrough

9.7 Verteilungssicht

9.7.1 Infrastruktur Windows

9.8 Konzepte

9.8.1 Abhängigkeiten zwischen Modulen

9.8.2 Schach-Domänenmodell

9.8.3 Benutzungsoberfläche

9.8.4 Plausibilisierung und Validierung

9.8.5 Ausnahme- und Fehlerbehandlung

9.8.6 Logging, Protokollierung, Tracing

9.8.7 Testbarkeit

9.9 Entwurfsentscheidungen

9.9.1 Wie kommuniziert die Engine mit der Außenwelt?

9.9.2 Sind Stellungsobjekte veränderlich oder nicht?

9.10 Qualitätsszenarien

9.10.1 Qualitätsbaum

9.10.2 Bewertungsszenarien

9.11 Risiken

9.11.1 Risiko: Anbindung an das Frontend

9.11.2 Risiko: Aufwand der Implementierung

9.11.3 Risiko: Erreichen der Spielstärke

9.12 Glossar

10 Stolpersteine der Architektur­dokumentation

10.1 Probleme

10.2 Fiese Fallen …

10.3 … und wie man sie umgeht oder entschärft

10.4 Reviews von Architekturdokumentation

Glossar

Literaturverzeichnis

Stichwortverzeichnis