Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Peter Götz
October 11, 2016

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.

Peter Götz

October 11, 2016
Tweet

More Decks by Peter Götz

Other Decks in Business

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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    https://pgoetz.de
    © Copyright 2016 Peter Götz
    Beispiele
    arc42-template-
    archetype
    • AsciiDoc
    • Maven
    • Git
    [Lafuente2014]

    View Slide

  12. +49 173 211 00 41 [email protected]
    https://pgoetz.de
    © Copyright 2016 Peter Götz
    Beispiele
    arc42-paver
    • Python
    • Markdown
    • Paver
    [Alcacer2016]

    View Slide

  13. +49 173 211 00 41 [email protected]
    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 [email protected]
    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 [email protected]
    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 [email protected]
    https://pgoetz.de
    © Copyright 2016 Peter Götz
    Fragen und Diskussion
    ? und
    !

    View Slide

  17. +49 173 211 00 41 [email protected]
    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