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

490 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
490
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

×