"Chef, Sie wollen schon wieder Doku von mir? Warum sollte ich die schreiben? Meine Teamkollegen und ich wissen schließlich auch ohne Doku, wie das System funktioniert und wo wir etwas ändern müssen. Doku hält mich nur vom Arbeiten ab! Und ... seien Sie mal ehrlich: Sie ist noch jedesmal runterpriorisiert worden, wenn es zeitlich eng wurde, also kann sie ja wohl nicht wichtig sein." -- Wollten Sie schon einmal solch einen Brief an Ihren Chef schreiben? Und haben dann doch zähneknirschend Ihr Word geöffnet? Lassen Sie sich in dieser praxisorientierten Session zeigen, wie Sie Architekturdokumentation mit Lust und minimalem Aufwand gestalten können (Gerüchte besagen, dass Markdown darin eine Rolle spielen wird).

1. Pah, Architekturdokumentation ...
darauf habe ich keine Lust!
Matthias Bohlen
http://mbohlen.de
@mbohlende
+49 170 772 8545
Asleep at the Wheel — Foto: Aaron Jacobs

2. Die verwunderten Entwickler
Eine Story aus dem
wirklichen Leben
Foto: GDC Europe

3. Ausreden: Wir haben doch schon…
Code Tests JavaDoc
Das ist doch bereits
unsere Doku – wozu
noch mehr?

4. Agilitäts-Missverständnis
Wir schätzen
"lauffähigen Code
mehr als vollständige
Dokumentation",
deshalb machen wir
keine !

5. wenig
Wir haben keine Lust
uncool langweilig dringend
Doku ist uncool
Das liest ja eh keiner
Anderes ist dringender
Fotos: woods Jiang, Felix, Hartwig HKD

6. Welcher Veraltet
Nutzen?
Zu viel
Aufwand
Echte Probleme
Dokumente sind oft
aufwändig, haben zu
geringen Nutzen, oder
sind veraltet.
Fotos: José Carlos da Silva Encarnação, Matt Brown, Renee

7. Doch Achtung!
Dokumentation hat
auch echte Vorteile!
Foto: Martin Fisch

8. Doku erleichtert die Einarbeitung
neuer Teammitglieder
Die Basics braucht
man dann nur einmal
zu erklären
Foto: tapetenpics

9. Doku beantwortet die Frage nach dem Warum
Warum etwas so
gemacht wurde, steht
meist weder im Code
noch in den Tests.
Foto: Anna Vignet

10. Doku macht Architektur nachvollziehbar
Eine dokumentierte
Architektur kann man
gegen Qualitätsziele
prüfen.
Foto: Wm Jas

11. Doku hilft, Fehler zu vermeiden
Sie wollen, dass Ihr
System rockt.
!
Und, dass das auch
so bleibt.
Foto: Christian Kadluba

12. Doku unterstützt beim Entwerfen
und beim Entwickeln
Wenn Sie etwas klar
aufschreiben müssen,
fokussiert das Ihre
Gedanken.
Foto: Jenn Kahalau

13. Doku unterstützt Kommunikation im Projekt
Am Whiteboard
streiten und einigen,
dann alles sauber
aufschreiben.
Foto: midnightcomm

14. Angemessene Doku macht das Team schneller
Doku-Investment Fokus auf die Arbeit
M. Bohlens Erfahrung aus Projekten – Alle Zahlen in Prozent der Teamkapazität

15. Die Lösung: Doku schrittweise angehen
7 Schritte
zum Doku-Erfolg
Foto: Shannon Kringen

16. 1. Den Doku-Kümmerer finden
Wie in der WG:
!
Einer muss für
Ordnung sorgen.
Foto: Liza

17. 2. Zielgruppe für Ihre Doku identifizieren
Wer sind Ihre
Stakeholder?
!
Was sagt Ihr
Vorgehensmodell?
!
Welche Rollen?
Welche Aufgaben?
Welche Ergebnisse?
Foto: Kevin Dooley

18. 18
Stakeholder und deren Anliegen
Rolle Anliegen
Projektleiter Technische Risiken, Arbeitsaufteilung
Entwickler Wie ist das Gesamtsystem aufgebaut?
Tester Wodurch wurde Qualität bereitgestellt?
Requirements
Analyst Wodurch sind die Anforderungen abgedeckt?
Betrieb Was bekommen wir zur Inbetriebnahme?
Wo sind die Überwachungs-Schnittstellen?
© ADOK Training Grundbegriffe

19. 3. Inhalte pro Zielgruppe festlegen
Wer hat welche
Belange und braucht
deshalb welche Sicht
auf das System?
!
Nicht jeder braucht
alles zu lesen !
Foto: Internet Archive Book

20. Dokumentationsmittel
Virtueller Produktkarton
Systemkontext
Qualitätsziele
Qualitätsszenario
Persona
Technische Risiken
Glossar
Architekturentscheidung
Bausteinsicht
Schnittstellenbeschreibung
Laufzeitsicht
Verteilungssicht
Übergreifende Konzepte
© ADOK Training Grundbegriffe 20

21. Notationen
UML-Diagramme
ER-Diagramme
Flussdiagramme
Hierarchische Bäume
Code-Beispiele
Prosa-Texte
Aufzählungen, Listen
Tabellen
!
!
Notation ist Form
!
!
Dokumentationsmittel
ist Aussage
© ADOK Training Grundbegriffe 21

22. 4. Medien zielgruppen-gerecht festlegen
Sind die Mitglieder
Ihrer Zielgruppe
visuell oder auditiv
veranlagt?
!
Bieten Sie entspre-chende
Medien an!
Foto: Frédéric BISSON

23. 5. Die Sache im Team machen, nicht einzeln
Jeder soll das zur
Doku beitragen, was
er/sie hat und was
einen Stakeholder
interessiert !
Foto: 드림포유

24. 6. Schreiben, ablegen, compilieren
Der kreative Prozess
!
Das sehen wir uns
gleich noch etwas
genauer an!
Foto: Roger H. Goun

25. 7. Verteilen und Feedback einholen
War die Doku hilfreich
für die Zielgruppe?
!
Was fehlt?
!
Was war zu viel?
!
Welche Darstellung
wäre noch hilfreicher?
Foto: woodleywonderworks

26. Der Erstellprozess für Dokumentation
class Erstellprozess
liest erzeugt
Autor Leser
schreibt in Build-Prozess liest
Repository Dokument
*
Dokumentationsmittel
extrahiert und
aggregiert

27. Beispiel-Toolkette für Erstellung und Ablage
Klartext mit Markup für
die Texte
UML-Werkzeug für die
oder
Abbildungen
Versionsmanagement-
System als Ablage
Typesetting Tool für die
Ausgabe
Konverter für eBooks

28. Demo
!
$ ./make.sh

29. Ergebnis: PDF
Kapitelnummern,
Seitennummern,
Inhaltsverzeichnis
!
Sehr gut lesbar
!
Souveräne
Seitenaufteilung
!
Navigierbar
Chapter 6
Runtime View
6.1 Code generation
These are the main steps (Figure 6.1) when AndroMDA generates code:
Figure 6.1: Overview of the entire code generation process
• The core is started by the build tool.
• The core discovers the components on the classpath and configures itself from an-dromda.
xml.
• A repository loads a model.
• A template engine loads a template.
• A template parses itself and searches for placeholders.
• When a placeholder is found, the template evaluates the expression that is contained
in the placeholder. It invokes a metafacade to obtain a value that is needed inside
the expression.
• The metafacade gets the raw model information from the PIM and transforms it into
a platform specific information.
• After the template has evaluated the placeholder expression, it replaces the place-holder
by the result of the evaluation.
14

30. Ergebnis: HTML
Keine Update-
Problematik
!
Für das Intranet
immer aktuell
!
Gut lesbar
!
Navigierbar

31. Ergebnis: eBook
Blättern wie im Buch
!
Gut lesbar
!
Navigierbar
!
Durchsuchbar
!
Annotierbar

32. Wenn Sie gute Doku auch für sich wollen…
Dann sehen Sie sich
mein kostenloses
Video-Training an:
!
!
!
!
!
Hier ist es:
http://bit.ly/rockt2014

33. Die Abkürzung zum Doku-Erfolg:
Advanced Level Workshop
mit Matthias Bohlen
!
Software-architektur
dokumentieren
!
24./25. November, Köln
Mehr Infos über diesen Workshop:
http://mbohlen.de/adok-de/

34. Coaching
nehmen
Seminar
besuchen
Newsletter
abonnieren
Beginnen Sie jetzt!
Newsletter, Blog,
Artikel, Bücher,
Podcast, Videos:
http://mbohlen.de
!
Anrufen:
+49 170 772 8545
Fotos: Pascual López, Friends of Europe, iStockPhoto