Architekturdokumentation leicht gemacht

Architektur und Dokumentation. Zwei schwergewichtige Worte in der Softwareentwicklung.

Während man sich bei der Softwareentwicklung schon gern mal Gedanken um eine vernünftige Architektur macht,
fällt die Dokumentation oftmals hinten runter.
Meist aus Mangel an Wissen, was man wie dokumentieren sollte und wo man die Informationen ablegt, sodass sie leicht wiedergefunden, gelesen und auch verstanden werden.

Doch das muss nicht sein. Dank des arc42 Templates für Architekturbeschreibungen erledigt sich die Frage nach dem Was und nach dem Wo bereits durch die bestehende Struktur.
Und die Frage nach dem Wie kann man mit etwas Übung und einigen Tipps und Tricks auch recht schnell beantworten.

Der Vortrag ist eine Einführung in das arc42 Architekturtemplate und gibt jedem Zuhörer das nötige Wissen an die Hand, die Architekturdokumentation ohne große Mühe in seinen bekannten Arbeitsablauf aufzunehmen.

Der Vortrag wurde am 09.05.2016 bei der Softwerkskammer Magdeburg gehalten.

Transcript

1. Architekturdokumentation leicht gemacht Andreas Richter ar@anrichter.net @anrichter www.anrichter.net
2. Architekturdokumentation Warum überhaupt Dokumentieren? Das arc42 Template Wie mach ich das nu? Ausblick
3. Warum überhaupt Dokumentieren?
4. • Was macht die Software eigentlich? • Was benötige ich für die Entwicklung? • Wo finde ich die Quellen & Beispieldaten? • Aus welchen Komponenten besteht die Lösung? • Wie arbeiten die Komponenten zusammen? • Warum wurde das so und nicht anders gelöst? • Worauf muss ich beim Entwickeln achten? Typische Fragen
5. • Der Funktionsumfang ist im Handbuch beschrieben • Steht alles in den Quellen. • Wie das Sytem arbeitet, sagt dir der Debugger. • Das ist historisch gewachsen. • Das machen wir schon immer so. • Das war schon so, als ich hier angefangen habe. Typische Antworten
6. • Antworten auf häufig gestellte Fragen • Container für Ergebnisse aus Architekturarbeit • Anforderungen und Randbedingungen klären • Strukturen entwerfen • Technische Konzepte entwerfen • Architektur kommunizieren • Umsetzung begleiten • Architektur bewerten Ziel einer Architekturdokumentation
7. Das arc42 Template
8. Warum überhaupt ein Template? • Projektübergreifend einheitliche Struktur • Schnelles Ablegen von Informationen • Schnelles Wiederfinden von Informationen • Umfassend • Kann als eine Art „Checkliste“ dienen
9. arc42 - Entstehung • 2005/2006 • Dr. Gernot Starke & Peter Hruschka • Reale Projekterfahrungen zusammengetragen • Mindmap-Übersicht architektonisch relevanter Themen • arc42-Template v2.1 (erste öffentliche Version 2006) • Bis heute (v6.0) kaum Änderungen an der Struktur
10. arc42 - Struktur 1. Einführung und Ziele 2. Randbedingungen 3. Kontextabgrenzung 4. Lösungsstrategie 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 8. Konzepte 9. Entwurfsentscheidungen 10. Qualitätsszenarien 11. Risiken 12. Glossar Anforderungsbezogene Informationen Strukturen der Lösung (Sichten) übergreifende (technische) Informationen Besonders wichtige Entscheidungen Legende:
11. 1. Einführung und Ziele 1.1. Aufgabenstellung • Kurzbeschreibung der Geschäftsprozesse • Funktionale Anforderungen 1.2 Qualitätsziele • 3-5 wichtigste Qualitätsziele • Nichtfunktionale Anforderungen 1.3 Stakeholder • Liste der wichtigsten Personen • Einfluss auf Architektur / System
12. 2. Randbedingungen 2.1 Technische Randbedingungen • Hard- und Software-Infrastruktur • Programmiersprachen / grafische Oberflächen 2.2 Organisatorische Randbedingungen • Organisation / Struktur • Ressourcen / Budget 2.3 Konventionen • Programmierrichtlinien • Namenskonventionen
13. 3. Kontextabgrenzung 3.1 Fachlicher Kontext • Logischer Informationsfluss mit Nachbarsystemen • Fachliches Kontextdiagramm cmp Fachlicher Kontext OTRS TFS Konnektor Open Ticket Request System (OTRS) Team Foundation Serv er (TFS) Supporter / Softwarentwickler TFS WorkItem OTRS Ticket Bedient
14. 3. Kontextabgrenzung 3.2 Technischer Kontext • Technische Kommunikation mit Nachbarsystemen • Deploymentdiagramm deployment Technischer Kontext TFSConnector VM OTRS VM HTTP HTTP HTTP OTRS TFS Konnektor HTTP HTTP HTTP HTTP Open Ticket Request System (OTRS) HTTP TFS VM HTTP Team Foundation Server (TFS) HTTP Supporter / Softwarentwickler Webseite TFS Client Object Model OTRS Generic Interface OTRS Generic Interface TFS Client Object Model
15. 3. Kontextabgrenzung 3.3 Externe Schnittstellen • Abhängigkeiten von Drittanbietern • Verweise auf externe Dokumentation • Auflistung verwendeter externer Schnittstellen
16. 4. Lösungsstrategie • Kurzer Überblick über • Grundlegende Entscheidung • Lösungsansätze
17. 5. Bausteinsicht • Statische Sicht auf Bausteine & deren Abhängigkeiten • Hierarchische Darstellung • Whitebox & Blackbox-Templates • Component-Diagramme & Erklärungen cmp OtrsService Whitebox UnityConfig Contracts OTRS - Http «Assembly» OtrsService UnityConfig Contracts OTRS - Http ISoapFactory IOtrsClient OtrsService ISoapFactory IOtrsClient UnityConfig SoapFactory ISoapFactory OtrsClient IOtrsClient RegisterComponents IOtrsService IConfig Models OTRS Generic Interface
18. 6. Laufzeitsicht • Zusammenarbeit der Bausteine zur Laufzeit • Nur die wichtigsten Szenarien • Tabellarisch • Interaction Diagramm & Erklärungen sd OtrsService - GetTicket OtrsService SoapFactory OtrsClient Open Ticket Request System (OTRS) Otrs Ticket aus Enevelope extrahieren() SessionId aus Envelope extrahieren() :HttpResponseMessage Post(Envelope) HttpClient.PostAsync() GetTicketGet(SessionToken) Post(Envelope) GetSessionCreate() :Envelope HttpClient.PostAsync() :HttpResponseMessage :Envelope :Envelope :Envelope
19. 7. Verteilungssicht • In welcher Umgebung läuft das System? • Wie wird es deployed & betrieben? • Deployment-Diagramm & Erklärungen deployment Infrastruktur TFS VM OTRS VM «executionEnvironment» IIS «executionEnvironment» IIS Open Ticket Request System (OTRS) OTRS TFS Konnektor Team Foundation Server (TFS) AdvantoWebservice.yml Anpassungen WorkItem Bug HTTP / SOAP HTTP / Client Object Model
20. 8. Konzepte • Übergreifende Themen und Konzepte • Auch Projektübergreifend • 8.1 Fachliche Strukturen (Domänenmodell) • 8.2 Typische Muster und Strukturen • 8.x Ablaufsteuerung • 8.x Logging • 8.x Fehlerbehandlung • 8.x Persistenz
21. 9. Entwurfsentscheidungen • Wesentliche Entscheidungen und deren Gründe Bildquelle: arc42.de
22. 10. Qualitätsszenarien • Verfeinert Qualitätsziele aus Kapitel 1.2 • Hilft bei der systematischen Bewertung der Architektur 10.1 Bewertungsszenarien • Nutzungsszenarien • Änderungsszenarien 10.2 Qualitätsbaum • Qualitätsbaum nach ATAM • Qualitätsszenarien an den Blättern
23. 11. Risiken • Priorisierte Liste von Risiken der Architektur • Hilft dem Projektmanagement • Zeigt eventuelle Probleme des Systems
24. 12. Glossar • Liste der wichtigsten Begriffe & deren Erklärung • Alphabetisch sortiert
25. Wie mach ich das nu?
26. Beispiele ansehen • Pro & Contra für eigene Projekte heraussuchen • DokChess – Stefan Zörner http://www.dokchess.de/ • biking2 – Michael Simons http://biking.michael-simons.eu/docs/index.html • arc42 by Example https://leanpub.com/arc42byexample
27. Ziele für Architekturdokumentation festlegen • Benötigen wir überhaupt eine Architekturdokumentation? • Worauf liegt der Fokus / Was ist uns wichtig? • Wer erstellt die Dokumentation? • Wer liest die Dokumentation?
28. Empfehlung für den Start • Neues System • 3. Kontextabgrenzung • 1.2 Qualitätsziele • 4. Lösungsstrategie • 8. Konzept • Fachliche Strukturen • Persistenz • UI • Verteilung • Bestehendes System • 5. Bausteinsicht • 6. Laufzeitsicht • 8.1 Fachliche Strukturen • 8.2 Typische Muster
29. Im laufenden Projekt • Iterativ / Inkrementell erweitern • Dokumentation als Teil der Definition of Done • Review der Dokumentation • Ausmisten! • Timeboxed Dokumentieren
30. Werkzeuge • Wiki • Markdown / Ascii-Doc Dateien • OneNote Notizbuch • Word Dokument im DMS • Diagrammerstellung • Zeichenwerkzeuge vs. Modellierungswerkzeuge • yEd - http://www.yworks.com/products/yed • Enterprise Architect - http://www.sparxsystems.de/
31. Ausblick
32. arc42 in großen Systemen • Hierarchie mehrerer arc42 Dokumentationen • Systemüberblick • 1. Einführung und Ziele • 2. Randbedingungen • 3. Kontextabgrenzung • 8. Konzepte • Subsystem 1 .. n • 5. Bausteinsicht • 6. Laufzeitsicht • 9. Entwurfsentscheidungen
33. Übung macht den Meister • Bausteinsicht für bestehendes System • Zeichen- vs. Modellierungswerkzeug • Kleines Side-Project inklusive Dokumentation • arc42 auf der grünen Wiese ausprobieren • Architektur-Katas • Architektur-Überlegungen in arc42 einsortieren
34. Quellen • arc42 - http://arc42.de/ • arc42 auf GitHub - http://arc42.github.io/ • DokChess - http://www.dokchess.de/ • „Softwarearchitekturen dokumentieren und kommunizieren“ Stefan Zörner • „arc42 by Example“ Gernot Starke, Michael Simons, Stefan Zörner
35. Vielen Dank! Andreas Richter ar@anrichter.net @anrichter www.anrichter.net