Continuous Documentation? Wie schaffen wir es, Entwicklungsteams für die Dokumentation von Softwarearchitektur zu begeistern?

Eine der großen Herausforderungen für Softwarearchitekten ist es, die Architekturdokumentation aktuell und in den Köpfen der Entwickler präsent zu halten. Manchmal gibt es nur eine lückenhafte oder nicht mehr aktuelle Dokumentation, oder die Entwicklungsteams wissen gar nicht, dass bestimmte Aspekte der Architektur dokumentiert sind und ignorieren sie deshalb.

Wir müssen also unsere Architekturdokumentation parallel zur Implementierung aktualisieren, korrigieren und erweitern. Und die beste Dokumentation liefert verschlossen im Tresor keinen großen Mehrwert, deshalb muss sie ständig verfügbar und leicht zu lesen sein. In dieser Session stelle ich verschiedene Möglichkeiten vor, Architekturdokumentation anzufertigen und abzulegen und gehe auf die Vor- und Nachteile ein. Außerdem zeige ich Möglichkeiten, um Entwicklungsteams in die Pflege und Weiterentwicklung der Architekturdokumentation einzubeziehen und dadurch gleichzeitig das Wissen um die gewählte Architektur zu verteilen.

Transcript

1. Continuous Documentation? Wie schaffen wir es, Entwicklungsteams für die Dokumentation von Softwarearchitektur zu begeistern?
2. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Referent • Peter Götz • Softwareentwickler und -architekt • Certified Professional for Software Architecture (Advanced Level) • Mitglied im iSAQB • Agiler Trainer & Coach • scrum.org Professional Scrum Trainer
3. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Wie denken wir? Scope Time Cost Projekt vs. Produkt
4. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Wo kommen wir her? Managing the Development of Large Software Systems (1970) „I believe in this concept, but the implementation described above is risky and invites failure.“ Dr. Winston W. Royce
5. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Was folgt daraus? • Architekturdokumentation zu Projektbeginn • Abnahme bei Phasenwechsel • Keine Aktualisierungen Lieber keine Dokumentation, als unzuverlässige Informationen Foo Bar Inc. Very Critical System Software Architecture Documentation Version 1.1 Last Update 17.10.2009
6. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Und die Lösung? 1. Barrieren und funktionale Silos abbauen 2. Entwicklungsteams einbinden 3. Architekturdokumentation im Entwicklungszyklus
7. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Funktionale Silos abbauen • Phasen aufbrechen • Zusammenarbeit statt Übergabe • Cross-funktionale Teams • Architektur als Teil des Produktlebenszyklus verstehen Anforderungen Architektur Design Implementierung Test Betrieb
8. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Entwicklungsteams einbinden • Raus aus dem Elfenbeinturm • Dokumentation übergeben • Teamverantwortlichkeit • “Doctator” [Kampenhout2009] Entwicklungsteam Software- architektur
9. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Entwickler dokumentieren Architektur Was? • Entwicklerwerkzeuge nutzen • Versionierung • Simplified UML [Zörner2012] Wie? • Textverarbeitung (z.B. MS Word) • Wiki (z.B. Confluence) • Markup (z.B. Markdown) + Versionskontrollsystem
10. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Beispiele arc42-gradle • Markdown • PlantUML • Gradle • Git [Götz2015]
11. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Beispiele arc42-template- archetype • AsciiDoc • Maven • Git [Lafuente2014]
12. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Beispiele arc42-paver • Python • Markdown • Paver [Alcacer2016]
13. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Beispiele arc42-template • Verschiedene Templates (AsciiDoc, DocBook, MS Word, ePUB, HTML, LaTex, Markdown, Textile) [Müller+2014]
14. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Beispiele arc42 Template for Confluence • Confluence Space mit Kapitelstruktur und Ausfüllhilfe • Original auf arc42.org [Starke+2012] • Add-On im Atlassian Marketplace [NetworkedAssets2016]
15. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Und jetzt? 1. Herausfinden, wie momentan Softwarearchitektur dokumentiert wird 2. Eine Möglichkeit finden, um die Dokumentation näher ans Team zu bringen 3. Möglichkeit umsetzen 4. Prüfen, ob die Verbesserung greift 5. Goto 1.
16. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Fragen und Diskussion ? und !
17. +49 173 211 00 41 peter.goetz@pgoetz.de https://pgoetz.de © Copyright 2016 Peter Götz Literaturverzeichnis [Alcacer2016] Dorian Alcacer-Labrador: https://github.com/dalcacer/arc42-paver [Götz2015] Peter Götz: https://github.com/p-goetz/arc42-gradle [Kampenhout2009] Niels van Kampenhout: Documentation: get it right!, ApacheCon Europe, Amsterdam 2009 (www.slideshare.net/nielsvk/documentation-talk-apachecon-eu-2009/) [Lafuente2014] Pedro Lafuente Blanco: https://github.com/plafue/arc42-template-archetype [Müller+2014] Ralf D. Müller, Gernot Starke u.A.: https://github.com/arc42/arc42-template [NetworkedAssets2016] NetworkedAssets: http://condoc.networkedassets.com/condoc/atc.html und https://github.com/NetworkedAssets/atc [Starke+2012] Gernot Starke, Peter Hruschka: http://confluence.arc42.org/display/LANDINGZON/landing+zone [Zörner2012] Stefan Zörner: Softwarearchitekturen dokumentieren und kommunizieren, Hanser 2012