1
Vortragsreihe Architekturdesign
Dokumentation – voll unagil? Software-Architekturen wirkungsvoll dokumentieren, Entwürfe und Entscheidungen nachvollziehbar festhalten
Stefan Zörner, oose Innovative Informatik GmbH
Embedded Software Engineering Kongress 2012
Sindelfingen, den 5. Dezember 2012
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Dokumentation – voll unagil?
Software-Architekturen wirkungsvoll dokumentieren, Entwürfe und
Entscheidungen nachvollziehbar festhalten
Kurzfassung
Dokumentation wird oft als lästige Pflicht angesehen und in vielen Softwareprojekten vernachlässigt. Die Architektur wird manchmal überhaupt nicht beschrieben. Dabei hilft gute Architekturdokumentation dabei, zentrale Ideen im Team und gegenüber anderen Beteiligten zu kommunizieren. In diesem Vortrag arbeite ich zunächst kurz heraus, welche Ziele Sie mit Architekturdokumentation generell verfolgen können. Anschließend stelle ich zentrale und bewährte Zutaten zum Festhalten architekturrelevanter Einflussfaktoren und wichtiger Entscheidungen vor. Ich zeige, wie Sie diese Ergebnisse zusammenstellen und ordnen können. Und ich diskutiere typische Werkzeugoptionen, um die Bestandteile zu erfassen, zu verwalten und zu verbreiten. Anhand der Gegenüberstellung von UML-Werkzeugen und Wikis werden die Stärken und Schwächen typischer Toolketten deutlich. Den Abschluss bilden Hinweise, die Ihnen helfen die häufigsten Fallen im Zusammenhang mit Dokumentation zu entschärfen.
2
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Stefan Zörner :: [email protected]
seit 2006 Berater und Trainer bei oose
Vorher IBM, Mummert + Partner, Bayer AG, …
Schwerpunkte:
Softwarearchitektur (Entwurf, Bewertung, Dokumentation)
Java Technologien
[email protected] ::@StefanZoerner :: [email protected]
Architekturdokumentation – voll unagil? oose.Innovative Informatik
1 Warum Softwarearchitekturen dokumentieren?
2 Die Aufgabe beschreiben
3 Die Lösung festhalten und kommunizieren
4 Lochen und abheften
5 Fazit und weitere Informationen
Agenda
3
Architekturdokumentation – voll unagil? oose.Innovative Informatik
1 1 Warum Softwarearchitekturen dokumentieren?
2 Die Aufgabe beschreiben
3 Die Lösung festhalten und kommunizieren
4 Lochen und abheften
5 Fazit und weitere Informationen
Agenda
Architekturdokumentation – voll unagil? oose.Innovative Informatik
? Fragen, die neue Mitarbeiter so stellen … (1)
Wo soll ich sitzen?
Was brauche ich für Tools?
Wie checke ich die Quelltexte aus, und
wie baue ich die Software?
Warum sind bei mir die Tests rot?
…
4
Architekturdokumentation – voll unagil? oose.Innovative Informatik
? Fragen, die neue Mitarbeiter so stellen … (2)
Ich finde mich nicht zurecht. Wie finde
ich einen Einstieg?
Diese Teile hier – wie arbeiten die
zusammen?
Ich soll hier neue Funktionalität
hinzufügen, wie stelle ich das an?
Ich habe hier etwas Ähnliches
gefunden, kann ich das
wiederverwenden?
…
Architekturdokumentation – voll unagil? oose.Innovative Informatik
? Fragen, die neue Mitarbeiter so stellen … (3)
Diese Software, an der wir hier arbeiten,
was macht die überhaupt?
Warum benutzen wir eigentlich noch
Linux 2.4?
Wieso habt Ihr das so gemacht? Ist das
nicht viel zu kompliziert?
Würde man das nicht eigentlich so
machen?
…
5
Architekturdokumentation – voll unagil? oose.Innovative Informatik
! Antworten, die neue Mitarbeiter erhalten …
Steht alles im Wiki.
Das haben wir nicht dokumentiert – wir
gehen agil vor.
Das war schon so, als ich neu war.
Das ist historisch gewachsen.
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Was ist Softwarearchitektur?
?
6
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Definitionen zu Softwarearchitektur
Es gibt nicht die eine allgemein akzeptierte Definition für Softwarearchitektur
Das Software Engineering Institute (SEI) sammelt sogar Definitionen:
http://www.sei.cmu.edu/architecture/definitions.html Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Was ist Softwarearchitektur?
Softwarearchitektur :=
wichtige Entscheidungen
wichtige Entscheidungen :=
fundamental
im weiteren Verlauf nur schwer zu ändern
Copyright 2012 :: Stefan Zörner :: oose GmbH
7
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Drei mögliche Ziele von Architekturdokumentation
Copyright 2011 :: Stefan Zörner :: oose GmbH © by oose innovative Informatik GmbH
Beim Entwurf der Architektur
unterstützen
Die Umsetzung und
Weiterentwicklung des Systems leiten
Die Architektur nachvollziehbar und
bewertbar machen
Architekturdokumentation – voll unagil? oose.Innovative Informatik
2 1 Warum Softwarearchitekturen dokumentieren?
2 Die Aufgabe beschreiben
3 Die Lösung festhalten und kommunizieren
4 Lochen und abheften
5 Fazit und weitere Informationen
Agenda
8
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Homepage ActiveMQ
9
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Architekturziele als Produktkarton
Was entwickeln wir eigentlich?
Was ist das zentrale Verkaufs- oder Nutzungsargument
("Claim", "Slogan")
Wem nützt es?
Was sind die wesentlichen Features des Systems?
Wie unterscheidet es sich von Produkten der Mitbewerber,
oder der Vorgängerversion?
Speziell für die Architektur
Welche Qualitätsmerkmale (= Ziele) sind besonders wichtig?
Welche Randbedingungen sind interessant?
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Beispiel: Ziele von „DokChess“
Sie dient als einfach zugängliches und
zugleich ungemein attraktives Fallbeispiel
für Architekturentwurf , -bewertung und
-dokumentation.
Der verständliche Aufbau lädt zum
Experimentieren und zum Erweitern der
Engine ein.
Ziel ist nicht die höchstmögliche Spielstärke
– dennoch gelingen Partien, die
Gelegenheitsspielern Freude bereiten.
http://www.dokchess.de
DokChess ist eine voll funktionsfähige Schach-Engine.
Copyright 2012 :: Stefan Zörner :: oose GmbH
10
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Systemkontext einer Online-Plattform
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Systemkontext „DokChess“
Die Kontextsicht zeigt das Umfeld, d.h. alle außerhalb
des eigenen Systems liegenden Benutzer und
Fremdsystem, mit denen direkt kommuniziert wird.
Copyright 2012 :: Stefan Zörner :: oose GmbH
11
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Systemkontext und Architekturziele
Was steckt drin? Was ist drum herum?
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
3 1 Warum Softwarearchitekturen dokumentieren?
2 Die Aufgabe beschreiben
3 Die Lösung festhalten und kommunizieren
4 Lochen und abheften
5 Fazit und weitere Informationen
Agenda
Copyright 2012 :: Stefan Zörner :: oose GmbH
12
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Was ist Softwarearchitektur? (Reloaded)
Architekturentscheidungen sind fundamental.
Diejenigen, die sich im weiteren Verlauf nur sehr
schwer revidieren lassen.
Konsequenzen: höhere Kosten, Zeitverlust, ggf.
scheitert das Vorhaben
“Software architecture is the set of
design decisions which, if made
incorrectly, may cause your project
to be cancelled.” (Eoin Woods)
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Entscheidungen treffen und festhalten. Ein Werkzeug
Copyright 2012 :: Stefan Zörner :: oose GmbH
13
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Leitfragen
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Zwei zentrale Entscheidungen in DokChess
Wie kommuniziert die Engine mit der Außenwelt?
Sind Stellungsobjekte veränderlich oder nicht?
http://www.dokchess.de/
Copyright 2012 :: Stefan Zörner :: oose GmbH
14
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Entscheidungen treffen + festhalten
http://www.swadok.de/
Probekapitel auf
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Analogie: Sichten (Views) auf Softwarearchitektur
Es ist sinnvoll, bestimmte Aspekte einer Software mit Bilder
statt textuell zu beschreiben
Ein einzelnes Bild reicht in der Regel nicht aus
Unterschiedliche Sichten für unterschiedliche Aspekte
Beispiel: Sichten in arc42
Kontextsicht
Bausteinsicht (= Struktur)
Laufzeitsicht (= Verhalten, Dynamik)
Verteilungssicht (= Deployment auf die
Zielumgebung)
Copyright 2012 :: Stefan Zörner :: oose GmbH
15
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Zusammenspiel Systemkontext und Zerlegung
Blackbox
Whitebox
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Zerlegung von DokChess in Subsysteme
Copyright 2012 :: Stefan Zörner :: oose GmbH
16
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Beispiel eines Ablaufes in DokChess
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
4 1 Warum Softwarearchitekturen dokumentieren?
2 Die Aufgabe beschreiben
3 Die Lösung festhalten und kommunizieren
4 Lochen und abheften
5 Fazit und weitere Informationen
Agenda
17
Architekturdokumentation – voll unagil? oose.Innovative Informatik
„Dokumentation“ als Fremdwort
Do|ku|men|ta|ti|on […zion] [lat.] die; -, -en:
1. a) Zusammenstellung u. Ordnung von Dokumenten
und Materialien jeder Art, durch die das Benutzen und
Auswerten ermöglicht oder erleichtert wird …
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Beispiele für Zutaten
Stellung
FeldZug
Figur
«enumeration»Farbe
«enumeration»FigurenArt
Copyright 2012 :: Stefan Zörner :: oose GmbH
18
Architekturdokumentation – voll unagil? oose.Innovative Informatik
arc42 – Vorschlag für eine Gliederung (Gernot Starke, Peter Hruschka)
http://www.arc42.de/
Architekturdokumentation – voll unagil? oose.Innovative Informatik
arc42
Copyright 2012 :: Stefan Zörner :: oose GmbH
19
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Beispiel für einen Architekturüberblick
http://www.dokchess.de/
Architekturdokumentation – voll unagil? oose.Innovative Informatik
UML = Unified Modeling Language
etablierte, standardisierte Notation im Bereich
Software-Engineering
http://www.uml.org/
Primäre Disziplinen:
Analyse
Entwurf / Architektur
umfangreich, 14
Diagrammtypen
Copyright 2012 :: Stefan Zörner :: oose GmbH
20
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Simplified Chinese
Simplified UML
Verwende nur wenige unterschiedliche
Modellelemente in Deinen UML-
Diagrammen, die aber korrekt.
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Idee hinter „Simplified UML”
Rückendeckung:
"One needs about 20% of the UML to attend to
80% of most modeling problems. So, there is
value in spending energy on what you can
remove from the UML rather than what you can
add."
(Grady Booch 2011, im persönlichen E-Mail-Austausch)
Leser ohne UML-Kenntnisse wird nicht von einer Symbolflut erschlagen
Leser mit UML-Kenntnissen finden sich auch zurecht
Sie profitieren trotzdem noch von wichtigen UML-Vorteilen
Copyright 2012 :: Stefan Zörner :: oose GmbH
21
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Diagramme == Sichten auf ein Modell
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Und im Wiki?
Copyright 2012 :: Stefan Zörner :: oose GmbH
22
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Die Werkzeugfrage …
Copyright 2012 :: Stefan Zörner :: oose GmbH
Konkrete Werkzeuge haben ihre Stärken in
einem, maximal 2 der Punkte.
Tools unterstützen in Architekturdokumentation beim …
Erstellen (insbesondere im Team) und Pflegen
Verwalten der Ergebnisse (Repository)
Kommunizieren der Inhalte an unterschiedliche Zielgruppen
Werkzeugfrage angehen wie eine Architekturentscheidung
Ziele? Randbedingungen? Risiken?
Alternativen (Wiki? UML-Tool? …)
Bewertung z.B. anhand Qualitätsszenarien
Architekturdokumentation – voll unagil? oose.Innovative Informatik
5 1 Warum Softwarearchitekturen dokumentieren?
2 Die Aufgabe beschreiben
3 Die Lösung festhalten und kommunizieren
4 Lochen und abheften
5 Fazit und weitere Informationen
Agenda
23
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Sieben Regeln für gute Dokumentation
1. Schreibe aus Sicht des Lesers
2. Vermeide unnötige Wiederholungen
3. Vermeide Mehrdeutigkeiten
3. a) Erkläre Deine Notation
4. Verwende eine Standardstrukturierung
5. Halte Begründungen für Entscheidungen fest
6. Halte Dokumentation aktuell, aber auch nicht zu aktuell
7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit
„Documenting Software Architectures: Views and
Beyond“
Clements, et.al, 2. Auflage 2010 Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Bücher zum Thema
Documenting Software Architectures:
Views and Beyond
Len Bass, Paul Clements, et al.
Addison Wesley, 2. Auflage Oktober 2010
Sprache: English (608 Seiten)
ISBN-13: 978-0321552686
Softwarearchitekturen dokumentieren und
kommunizieren
Entwürfe, Entscheidungen und Lösungen
nachvollziehbar und wirkungsvoll festhalten
Stefan Zörner, Geleitwort von Gernot Starke
Hanser Fachbuch, Mai 2012
Sprache: Deutsch (ca. 280 Seiten)
ISBN-13: 978-3446429246
Copyright 2012 :: Stefan Zörner :: oose GmbH
24
Architekturdokumentation – voll unagil? oose.Innovative Informatik
Copyright 2012 :: Stefan Zörner :: oose GmbH
!
Beginnen Sie bereits während des
Entwurfs damit, Ihre Lösungsideen
und Entscheidungen festzuhalten. (anstatt sie zu vergessen)
Vielen Dank!
Ich freue mich auf Ihre Fragen! [email protected]
? ? ?
Top Related