historisch gewachsen?...und wie man sie macht. stefan zörner :: @stefanzoerner :: [email protected]...
TRANSCRIPT
1
ddc_conference #ddc12 www.dotnet-developer-conference.de
Historisch gewachsen?
Architekturdokumentation: Warum sie wichtig ist. Und wie man sie
macht.
Stefan Zörner :: @StefanZoerner :: [email protected]
ddc_conference #ddc12 www.dotnet-developer-conference.de
Historisch gewachsen?
Stefan Zörner: „Historisch gewachsen?“ Architekturdokumentation: Warum sie wichtig ist. Und wie man sie macht.
Dokumentieren zählt nicht unbedingt zu den Lieblingsbeschäftigungen eines Entwicklers. Und dann auch noch Architektur? Kästchen, Linien, Wolken? Wirkungsvolle Architekturdokumentation ist keine bunte High-Level Powerpoint-Präsentation. Sie macht zentrale Entscheidungen auch später noch nachvollziehbar.
In diesem Vortrag erfahren Sie, wie Sie Ihre Architektur geeignet festhalten, anstatt sie zu vergessen. Für Neue im Team haben Sie anschließend bessere Antworten parat als “Historisch gewachsen”.
Zielgruppe
Zielgruppe dieses Vortrags sind in erster Linie Softwarearchitekten und Entwickler. Sie sollten Erfahrungen in IT-Projekten gesammelt haben; Kenntnisse in einer bestimmten Technologie oder Programmiersprache sind zum Verständnis nicht erforderlich.
2
Architekturdokumentation – Historisch gewachsen? 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 – Historisch gewachsen? 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 – Historisch gewachsen? 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 – Historisch gewachsen? 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 – Historisch gewachsen? 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? Habt Ihr das irgendwo
aufgemalt?
Ich soll hier neue Funktionalität
hinzufügen, wie stelle ich das an?
Ich habe hier etwas Ähnliches
gefunden, kann ich das
wiederverwenden?
…
Architekturdokumentation – Historisch gewachsen? 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
.NET 2.0?
Wieso habt Ihr das so gemacht? Ist das
nicht viel zu kompliziert?
Würde man das nicht eigentlich so
machen?
…
5
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
6
Architekturdokumentation – Historisch gewachsen? 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 – Historisch gewachsen? oose.Innovative Informatik
Was ist Softwarearchitektur?
?
7
Architekturdokumentation – Historisch gewachsen? 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
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Eine (!) Definition. Unsere.
Softwarearchitektur :=
wichtige Entscheidungen
wichtige Entscheidungen :=
fundamental
im weiteren Verlauf nur schwer zu ändern
8
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Idealbild: Architekturüberblick auf < 30 Seiten
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Implementierung des Idealbildes?
arc42 -- Vorschlag für ein Template (Gernot Starke, Peter Hruschka)
http://www.arc42.de/
9
Architekturdokumentation – Historisch gewachsen? 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
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
!
Copyright 2012 :: Stefan Zörner :: oose GmbH
Vor dem Anfertigen jeglicher
Dokumentation stehen die Fragen
„Für wen?“und „Weshalb?“.
Wer sind unsere Zielgruppen?
Welchen Zweck verfolgen wir mit der
Dokumentation?
10
Architekturdokumentation – Historisch gewachsen? 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 – Historisch gewachsen? 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
11
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Homepage ActiveMQ
Architekturdokumentation – Historisch gewachsen? 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?
12
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Beispiel: Schach-Engine „DokChess“
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? 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
13
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
!
Copyright 2012 :: Stefan Zörner :: oose GmbH
Jede Architekturbeschreibung,
ganz gleich ob Dokument oder
Präsentation, beginnt mit der
Aufgabenstellung.
Das Anfertigen eines virtuellen
Produktkartons mit Slogan ist dabei
sehr hilfreich.
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
14
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
node.js?
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Systemkontext einer Online-Plattform
Copyright 2012 :: Stefan Zörner :: oose GmbH
15
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Systemkontext „DokChess“
Die Kontextsicht zeigt das Umfeld, d.h. alle außerhalb
des eigenen Systems liegenden Benutzer und
Fremdsysteme, mit denen direkt kommuniziert wird.
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? 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
16
Architekturdokumentation – Historisch gewachsen? 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)
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Entscheidungen treffen und festhalten. Ein Werkzeug
17
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Leitfragen
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
!
Copyright 2012 :: Stefan Zörner :: oose GmbH
Zentrale Entscheidungen
nachvollziehbar festhalten ist der
Schlüssel, um bessere Antworten zu
haben als „Historisch gewachsen“.
Sich an der Entscheidungsmindmap
entlang zu hangeln gibt Orientierung.
18
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Zwei zentrale Entscheidungen in DokChess
Wie kommuniziert die Engine mit der Außenwelt? (den Gegnern)
Sind Stellungsobjekte veränderlich oder nicht?
http://www.dokchess.de/
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
19
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Analogie: Sichten (Views) auf Softwarearchitektur
Es ist sinnvoll, bestimmte Aspekte einer Software mit Bildern
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)
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Zusammenspiel Systemkontext und Zerlegung
Blackbox
Whitebox
20
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Zerlegung von DokChess in Subsysteme
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Beispiel für einen Ablauf
21
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
!
Copyright 2012 :: Stefan Zörner :: oose GmbH
Innerhalb Eures Vorhabens die
Begriffe der Zerlegung klären und
dann konsistent verwenden.
(Auch in der Dokumentation.)
22
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
System „DokChess“, vier Subsysteme
Architekturdokumentation – Historisch gewachsen? 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
23
Architekturdokumentation – Historisch gewachsen? 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 …
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Vom pragmatischen Umgang mit Gliederungen
Architekturdokumentation != ein Template ausfüllen
Gliederungsvorschläge (z.B. arc42) motivieren Inhalte
können Orientierung geben, wie Sie vorgehen
Für Arbeitsergebnisse entscheidet Ihr Euch explizit
Welche Inhalte erstellen Sie?
Für wen? (Zielgruppe)
In welcher Tiefe? (detailliert? Überblick?)
Die Zielgruppen sind entscheidend für die
Zutaten die Sie erstellen, und auch die Tiefe. Copyright 2012 :: Stefan Zörner :: oose GmbH
24
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Zuordnung von Zielgruppen zu Inhalten
Inhalt 1 Inhalt 2 Inhalt 3 Inhalt 4 …
Auftraggeber Überblick Überblick
Architekturteam Überblick detailliert
Entwickler Überblick detailliert detailliert
Tester Überblick
… Beispielzielgruppen!
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Beispiele für Inhalte (Zutaten)
Stellung
FeldZug
Figur
«enumeration»Farbe
«enumeration»FigurenArt
25
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
arc42
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Beispiel: Wiki als Repository für Zutaten
Copyright 2012 :: Stefan Zörner :: oose GmbH
26
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Beispiel: Rekombinieren im Confluence-Wiki
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Die Werkzeugfrage …
Konkrete Werkzeuge haben ihre Stärken in
einem, maximal zwei der drei 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? …)
…
27
Architekturdokumentation – Historisch gewachsen? 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
Architekturdokumentation – Historisch gewachsen? 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
28
Architekturdokumentation – Historisch gewachsen? 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
Ihr profitiert trotzdem noch von wichtigen UML-Vorteilen
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Diagramme == Sichten auf ein Modell
Copyright 2012 :: Stefan Zörner :: oose GmbH
29
Architekturdokumentation – Historisch gewachsen? 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
Architekturdokumentation – Historisch gewachsen? 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
30
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Reviews
Ein Review ist die Begutachtung von Ergebnissen (oder
Zwischenergebnissen) durch Personen, die nicht an der
Erstellung beteiligt waren. Das können Teammitglieder
innerhalb des Vorhabens sein, oder auch Außenstehende.
Regel 7: „Überprüfe Dokumentation auf
Gebrauchstauglichkeit."
(aus „Sieben Regeln für gute Dokumentation“)
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Ziele beim Review
Grundsätzlich könnt Ihr überprüfen, ob eine
Dokumentation …
konform zu bestimmten Standards ist.
die Arbeit mit der Architektur unterstützt
(Gebrauchstauglichkeit).
eine Bewertung der Architektur unterstützt
(Analysierbarkeit, Nachvollziehbarkeit).
31
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Copyright 2012 :: Stefan Zörner :: oose GmbH
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
32
Architekturdokumentation – Historisch gewachsen? 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
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Beispiel für einen Architekturüberblick
http://www.dokchess.de/
33
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Entscheidungen treffen + festhalten
http://www.swadok.de/
Probekapitel auf
Architekturdokumentation – Historisch gewachsen? oose.Innovative Informatik
Copyright 2012 :: Stefan Zörner :: oose GmbH
!
Beginnt bereits während des Entwurfs
damit, Eure Lösungsideen und
Entscheidungen festzuhalten. (anstatt sie zu vergessen)
34
ddc_conference #ddc12 www.dotnet-developer-conference.de
Vielen Dank!
Ich freue mich auf Eure Fragen!
Stefan Zörner, @StefanZoerner, [email protected]
? ? ?