Architekturdokumentation leicht gemacht

Transkript

1 Architekturdokumentation leicht gemacht Andreas

2 Architekturdokumentation Warum überhaupt Dokumentieren? Das arc42 Template Wie mach ich das nu? Ausblick

3 Warum überhaupt Dokumentieren?

4 Typische Fragen 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?

5 Typische Antworten 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.

6 Ziel einer Architekturdokumentation 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

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 9. Entwurfsentscheidungen 4. Lösungsstrategie 10. Qualitätsszenarien 5. Bausteinsicht 6. Laufzeitsicht 7. Verteilungssicht 11. Risiken 8. Konzepte 12. Glossar Legende: Anforderungsbezogene Informationen Strukturen der Lösung (Sichten) übergreifende (technische) Informationen Besonders wichtige Entscheidungen

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 & Textuelle Erläuterung

14 3. Kontextabgrenzung 3.2 Technischer Kontext Technische Kommunikation mit Nachbarsystemen Deploymentdiagramm & Textuelle Erklärung

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 zum Lösungsansatz Inklusive Begründung Verweis auf Randbedingungen, Entwurfsentscheidung,

17 5. Bausteinsicht Statische Sicht auf Bausteine & deren Abhängigkeiten Hierarchische Darstellung Whitebox & Blackbox-Templates Component-Diagramme & Textuelle Erklärungen

18 6. Laufzeitsicht Zusammenarbeit der Bausteine zur Laufzeit Nur die wichtigsten Szenarien Tabellarisch Interaction Diagramm & Erklärungen

19 7. Verteilungssicht In welcher Umgebung läuft das System? Wie wird es deployed & betrieben? Deployment-Diagramm & Erklärungen

20 8. Konzepte Übergreifende Themen und Konzepte Auch Projektübergreifend 8.1 Fachliche Strukturen (Domänenmodell) 8.2 Typische Muster 8.x Ablaufsteuerung 8.x Logging 8.x Fehlerbehandlung 8.x Persistenz 8.x

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 biking2 Michael Simons arc42 by Example

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 Dokumentation als Teil der Definition of Done Review der Dokumentation Ausmisten! Timeboxed Faul & Sparsam

30 Werkzeuge Wiki Markdown / Ascii-Doc Dateien OneNote Notizbuch Word Dokument im DMS Diagrammerstellung Zeichenwerkzeuge vs. Modellierungswerkzeuge yed - Enterprise Architect -

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 arc arc42 auf GitHub - DokChess - Softwarearchitekturen dokumentieren und kommunizieren Stefan Zörner arc42 by Example Gernot Starke, Michael Simons, Stefan Zörner

35 Vielen Dank! Andreas