"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).
WJAX 2014: Pah, ArchitekturDoku, darauf habe ich keine Lust!
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
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
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
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
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
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
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/