Pah, Architekturdokumentation ... 
darauf habe ich keine Lust! 
Matthias Bohlen 
http://mbohlen.de 
@mbohlende 
+49 170 77...
Die verwunderten Entwickler 
Eine Story aus dem 
wirklichen Leben 
Foto: GDC Europe
Ausreden: Wir haben doch schon… 
Code Tests JavaDoc 
Das ist doch bereits 
unsere Doku – wozu 
noch mehr?
Agilitäts-Missverständnis 
Wir schätzen 
"lauffähigen Code 
mehr als vollständige 
Dokumentation", 
deshalb machen wir 
ke...
wenig 
Wir haben keine Lust 
uncool langweilig dringend 
Doku ist uncool 
Das liest ja eh keiner 
Anderes ist dringender 
...
Welcher Veraltet 
Nutzen? 
Zu viel 
Aufwand 
Echte Probleme 
Dokumente sind oft 
aufwändig, haben zu 
geringen Nutzen, ode...
Doch Achtung! 
Dokumentation hat 
auch echte Vorteile! 
Foto: Martin Fisch
Doku erleichtert die Einarbeitung 
neuer Teammitglieder 
Die Basics braucht 
man dann nur einmal 
zu erklären 
Foto: tapet...
Doku beantwortet die Frage nach dem Warum 
Warum etwas so 
gemacht wurde, steht 
meist weder im Code 
noch in den Tests. 
...
Doku macht Architektur nachvollziehbar 
Eine dokumentierte 
Architektur kann man 
gegen Qualitätsziele 
prüfen. 
Foto: Wm ...
Doku hilft, Fehler zu vermeiden 
Sie wollen, dass Ihr 
System rockt. 
! 
Und, dass das auch 
so bleibt. 
Foto: Christian K...
Doku unterstützt beim Entwerfen 
und beim Entwickeln 
Wenn Sie etwas klar 
aufschreiben müssen, 
fokussiert das Ihre 
Geda...
Doku unterstützt Kommunikation im Projekt 
Am Whiteboard 
streiten und einigen, 
dann alles sauber 
aufschreiben. 
Foto: m...
Angemessene Doku macht das Team schneller 
Doku-Investment Fokus auf die Arbeit 
M. Bohlens Erfahrung aus Projekten – Alle...
Die Lösung: Doku schrittweise angehen 
7 Schritte 
zum Doku-Erfolg 
Foto: Shannon Kringen
1. Den Doku-Kümmerer finden 
Wie in der WG: 
! 
Einer muss für 
Ordnung sorgen. 
Foto: Liza
2. Zielgruppe für Ihre Doku identifizieren 
Wer sind Ihre 
Stakeholder? 
! 
Was sagt Ihr 
Vorgehensmodell? 
! 
Welche Roll...
18 
Stakeholder und deren Anliegen 
Rolle Anliegen 
Projektleiter Technische Risiken, Arbeitsaufteilung 
Entwickler Wie is...
3. Inhalte pro Zielgruppe festlegen 
Wer hat welche 
Belange und braucht 
deshalb welche Sicht 
auf das System? 
! 
Nicht ...
Dokumentationsmittel 
Virtueller Produktkarton 
Systemkontext 
Qualitätsziele 
Qualitätsszenario 
Persona 
Technische Risi...
Notationen 
UML-Diagramme 
ER-Diagramme 
Flussdiagramme 
Hierarchische Bäume 
Code-Beispiele 
Prosa-Texte 
Aufzählungen, L...
4. Medien zielgruppen-gerecht festlegen 
Sind die Mitglieder 
Ihrer Zielgruppe 
visuell oder auditiv 
veranlagt? 
! 
Biete...
5. Die Sache im Team machen, nicht einzeln 
Jeder soll das zur 
Doku beitragen, was 
er/sie hat und was 
einen Stakeholder...
6. Schreiben, ablegen, compilieren 
Der kreative Prozess 
! 
Das sehen wir uns 
gleich noch etwas 
genauer an! 
Foto: Roge...
7. Verteilen und Feedback einholen 
War die Doku hilfreich 
für die Zielgruppe? 
! 
Was fehlt? 
! 
Was war zu viel? 
! 
We...
Der Erstellprozess für Dokumentation 
class Erstellprozess 
liest erzeugt 
Autor Leser 
schreibt in Build-Prozess liest 
R...
Beispiel-Toolkette für Erstellung und Ablage 
Klartext mit Markup für 
die Texte 
UML-Werkzeug für die 
oder 
Abbildungen ...
Demo 
! 
$ ./make.sh
Ergebnis: PDF 
Kapitelnummern, 
Seitennummern, 
Inhaltsverzeichnis 
! 
Sehr gut lesbar 
! 
Souveräne 
Seitenaufteilung 
! ...
Ergebnis: HTML 
Keine Update- 
Problematik 
! 
Für das Intranet 
immer aktuell 
! 
Gut lesbar 
! 
Navigierbar
Ergebnis: eBook 
Blättern wie im Buch 
! 
Gut lesbar 
! 
Navigierbar 
! 
Durchsuchbar 
! 
Annotierbar
Wenn Sie gute Doku auch für sich wollen… 
Dann sehen Sie sich 
mein kostenloses 
Video-Training an: 
! 
! 
! 
! 
! 
Hier i...
Die Abkürzung zum Doku-Erfolg: 
Advanced Level Workshop 
mit Matthias Bohlen 
! 
Software-architektur 
dokumentieren 
! 
2...
Coaching 
nehmen 
Seminar 
besuchen 
Newsletter 
abonnieren 
Beginnen Sie jetzt! 
Newsletter, Blog, 
Artikel, Bücher, 
Pod...
Nächste SlideShare
Wird geladen in …5
×

WJAX 2014: Pah, ArchitekturDoku, darauf habe ich keine Lust!

474 Aufrufe

Veröffentlicht am

"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).

Veröffentlicht in: Business
0 Kommentare
1 Gefällt mir
Statistik
Notizen
  • Als Erste(r) kommentieren

Keine Downloads
Aufrufe
Aufrufe insgesamt
474
Auf SlideShare
0
Aus Einbettungen
0
Anzahl an Einbettungen
30
Aktionen
Geteilt
0
Downloads
0
Kommentare
0
Gefällt mir
1
Einbettungen 0
Keine Einbettungen

Keine Notizen für die Folie

WJAX 2014: Pah, ArchitekturDoku, darauf habe ich keine Lust!

  1. 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. 2. Die verwunderten Entwickler Eine Story aus dem wirklichen Leben Foto: GDC Europe
  3. 3. Ausreden: Wir haben doch schon… Code Tests JavaDoc Das ist doch bereits unsere Doku – wozu noch mehr?
  4. 4. Agilitäts-Missverständnis Wir schätzen "lauffähigen Code mehr als vollständige Dokumentation", deshalb machen wir keine !
  5. 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. 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. 7. Doch Achtung! Dokumentation hat auch echte Vorteile! Foto: Martin Fisch
  8. 8. Doku erleichtert die Einarbeitung neuer Teammitglieder Die Basics braucht man dann nur einmal zu erklären Foto: tapetenpics
  9. 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. 10. Doku macht Architektur nachvollziehbar Eine dokumentierte Architektur kann man gegen Qualitätsziele prüfen. Foto: Wm Jas
  11. 11. Doku hilft, Fehler zu vermeiden Sie wollen, dass Ihr System rockt. ! Und, dass das auch so bleibt. Foto: Christian Kadluba
  12. 12. Doku unterstützt beim Entwerfen und beim Entwickeln Wenn Sie etwas klar aufschreiben müssen, fokussiert das Ihre Gedanken. Foto: Jenn Kahalau
  13. 13. Doku unterstützt Kommunikation im Projekt Am Whiteboard streiten und einigen, dann alles sauber aufschreiben. Foto: midnightcomm
  14. 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. 15. Die Lösung: Doku schrittweise angehen 7 Schritte zum Doku-Erfolg Foto: Shannon Kringen
  16. 16. 1. Den Doku-Kümmerer finden Wie in der WG: ! Einer muss für Ordnung sorgen. Foto: Liza
  17. 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. 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. 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. 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. 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. 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. 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. 24. 6. Schreiben, ablegen, compilieren Der kreative Prozess ! Das sehen wir uns gleich noch etwas genauer an! Foto: Roger H. Goun
  25. 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. 26. Der Erstellprozess für Dokumentation class Erstellprozess liest erzeugt Autor Leser schreibt in Build-Prozess liest Repository Dokument * Dokumentationsmittel extrahiert und aggregiert
  27. 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. 28. Demo ! $ ./make.sh
  29. 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. 30. Ergebnis: HTML Keine Update- Problematik ! Für das Intranet immer aktuell ! Gut lesbar ! Navigierbar
  31. 31. Ergebnis: eBook Blättern wie im Buch ! Gut lesbar ! Navigierbar ! Durchsuchbar ! Annotierbar
  32. 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. 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. 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

×