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?
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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]
    

    View Slide

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]
    

    View Slide

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]
    

    View Slide

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]
    

    View Slide

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]
    

    View Slide

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.
    

    View Slide

16. +49 173 211 00 41 peter.goetz@pgoetz.de
    https://pgoetz.de
    © Copyright 2016 Peter Götz
    Fragen und Diskussion
    ? und
    !
    

    View Slide

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
    

    View Slide