Moderne Softwarearchitekturen dokumentieren und kommunizieren

JCON 2021, https://jcon.sched.com/event/721c133fed5d1daf4dabc46e1e8fe546 zusammen mit Falk Sippach

Unsere Software-Projekte werden immer größer und komplexer. Technologisch hat sich in den vergangenen Jahren eine Menge getan, um diese Komplexität in den Griff zu bekommen. Aber noch viel wichtiger ist die Kommunikation zwischen allen Projektbeteiligten geworden. Als Voraussetzung braucht es dafür eine möglichst aktuelle, pragmatische und zielführende Dokumentation der Softwarearchitektur. Aber leider hat das Dokumentieren häufig einen niedrigen Stellenwert in unseren Projekten. Zum Teil fehlt die Motivation bei den Verantwortlichen. Oder suboptimale Werkzeuge wie Textverarbeitung, schwergewichtige UML-Tools bzw. Wikis ersticken alle Bemühungen im Keim. Wir wollen den Bann brechen und an konkreten Beispielen zeigen, wie Dokumentieren nicht nur Spaß machen, sondern auch leicht von der Hand gehen kann. Dazu berichten wir aus unseren Erfahrungen und rücken leichtgewichtige Tools und schlanke Text- bzw. Grafikformate in den Fokus. Sie erleichtern die automatisierte Erstellung einer effektiven, allumfänglichen und vor allem redundanzfreien Dokumentation, die sich mit wenig Aufwand für die unterschiedlichen Zielgruppen optimiert in verschiedenen Formaten ausliefern lässt. Das Einbetten dieser Documentation as Code in die Entwicklungs- und Reviewprozesse ermöglicht zudem eine gute Nachvollziehbarkeit und die kontinuierliche Verbesserung und Weiterentwicklung.

Transcript

1. Moderne Software- architektur- dokumentation Falk Sippach embarc Ralf D. Müller DB Systel GmbH
2. fs@embarc.de @sippsack ➔ xing.to/fsi Falk Sippach ◼ Softwarearchitekt, Berater, Trainer bei embarc ◼ früher bei Orientation in Objects (OIO), Trivadis
3. ralf.d.mueller@deutschebahn.com @ralfdmueller ➔ xing.to/rdmuller Ralf D. Müller ◼ was mit Dokumentation, Security und Architektur by der DB Systel ◼ Maintainer von docToolchain, Contributor arc42 ◼ co-Autor
5. Mission Statement(für diesen Vortrag) ▪ Klären, was man von der Softwarearchitektur dokumentieren sollte und wie uns arc42 bei der Strukturierung hilft. ▪ Umsetzung des Documentation-as-Code Ansatzes mit docToolchain ▪ Überblick über die sehr effektiven Funktionen von AsciiDoctor und dessen mächtigen Integrationsmöglichkeiten im Umfeld von Architekturdokumentation
6. Agenda • Einführung • Architektur dokumentieren • Ein Reifegradmodell • Fazit und Ausblick
7. Agenda • Einführung • Architektur dokumentieren • Ein Reifegradmodell • Fazit und Ausblick
8. 10 aus: Effektive Softwarearchitekturen (G. Starke) Architektur bewerten Architektur kommunizieren Architektur entwerfen Anforderungen klären Architektur kommunizieren
9. 11 Entwurfsunterstützung Kommunikation Neue Mitarbeiter Frage nach dem Warum Bewertbarkeit Grafik von The Practical Dev (CC0 Public Domain Lizenz)
10. Hauptsache, du machst es nicht mit Word!
11. Ungeeignete Werkzeuge Medienbruch Dateiablage Redundanzen Textwüsten Handarbeit Veraltet Liest sowieso keiner!
12. 14 • Plain-Text • Entwicklungsumgebung • Kommandozeilen- werkzeuge • Versionsverwaltung Unser täglich Entwickler-Brot Foto von geralt: https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/ (CC0 Public Domain Lizenz)
13. Documentation-as-Code Ablage im Repo Versionier- /Diffbar Synchrone Auslieferung Offlinefähig Teil des Build- Prozesses Generierung/ Automatisierung Flexible Ausgabe Nähe zum Sourcecode
14. Continuous Documentation Automatisiert erstellen Regelmäßig ausliefern Stetig ergänzen Reviewen Feedback integrieren
15. Agenda • Einführung • Architektur dokumentieren • Ein Reifegradmodell • Fazit und Ausblick
16. 7 Regeln für gute Dokumentation 1. Schreibe aus Sicht des Lesers 2. Vermeide unnötige Wiederholungen 3. Vermeide Mehrdeutigkeiten 3. a) Erkläre Deine Notation 4. Verwende eine Standardstrukturierung 5. Halte Begründungen für Entscheidungen fest 6. Halte die Dokumentation aktuell, aber auch nicht zu aktuell 7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit „Documenting Software Architectures: Views and Beyond“ Clements, et.al, 2. Auflage 2010
17. 7 Regeln für gute Dokumentation 1. Schreibe aus Sicht des Lesers 2. Vermeide unnötige Wiederholungen 3. Vermeide Mehrdeutigkeiten 3. a) Erkläre Deine Notation 4. Verwende eine Standardstrukturierung 5. Halte Begründungen für Entscheidungen fest 6. Halte die Dokumentation aktuell, aber auch nicht zu aktuell 7. Überprüfe Dokumentation auf ihre Gebrauchstauglichkeit „Documenting Software Architectures: Views and Beyond“ Clements, et.al, 2. Auflage 2010
18. „Abheften“ in arc42 ➔https://arc42.de/ Dr. Peter Hruschka http://www.peterhruschka.eu/ Dr. Gernot Starke http://gernotstarke.de/
19. 1. Requirements & Goals 2. Constraints 3. Scope & Context 4. Solution Strategy 5. Building Block View 6. Runtime View 7. Deployment View 10. Quality Scenarios 11. Risks & Tech Debt 12. Glossary 9. Decisions 8. Crosscutting Concepts
20. Wald vor lauter Bäumen …
21. Architekturentwurf Anforderungen Lösungsansätze
22. Was ist ein Architekturüberblick? Ein Architekturüberblick macht die zentralen Lösungsansätze Eurer Softwarearchitektur für Außenstehende nachvollziehbar. Teamfremde Kollegen Entscheider Stakeholder Neue Teammitglieder
24. Mission Statement Die Corona-Warn-App ist eine App, die hilft, Infektionsketten des SARS-CoV-2 (COVID-19-Auslöser) in Deutschland nachzuverfolgen und zu unterbrechen. Die App basiert auf Technologien mit einem dezentralisierten Ansatz und informiert Personen, wenn sie mit einer infizierten Person in Kontakt standen. Transparenz ist von entscheidender Bedeutung, um die Bevölkerung zu schützen und die Akzeptanz zu erhöhen. Quelle: https://www.coronawarn.app/de/
25. Architektur CWA: Informelles Überblicksbild
26. Kontextabgrenzung Dieser fachliche Systemkontext zeigt das Corona-Warn-App-System im Zusammenspiel mit den wichtigsten Benutzern und Fremdsystemen. Benutzer CWA-System stellt Oberfläche bereit Fremdsystem CWA-System stellt Schnittstelle(n) bereit Legende:
27. Technologie-Stack Vorgehen CWA – Konkrete Entscheidungen Zerlegung Client/Server mit Apps und Backend-Server als verteilte Menge einzeln deploybarer Services, fachlich zerlegt (Test- ergebnisse, Verifikation …) Zielumgebung Clients: Smartphones der Endnutzer, Backend: Kubernetes in der Telekom- Cloud … Native Apps in Swift und Kotlin auf iOS und Android. Backend in Java mit Spring Boot, Postgres, … Entwicklung als Open Source, Quelltexte in GitHub, Dokumentation in Markdown, automatisierte Tests ...
28. Technologie-Stack • Native Clients in Swift bzw. Kotlin für iOS und Android • SQLite • Java 11 • Spring Boot/Cloud/Data • Lombok, Guava, … • REST, Protobuf • OpenAPI, Micrometer • Liquibase • Maven, Gradle • Docker, Kubernetes • Open Telekom Cloud (OpenStack) • PostgreSQL, S3, CDN • Keycloak
29. Einflüsse auf Entscheidungen - schränken die Lösung ein - schließen Optionen aus Vorgaben/Rahmenbedingungen Technisch (z.B. Datenbankprodukt) Organisatorisch (z.B. Team)
30. Zentrale Rahmenbedingungender CWA Organisatorisch ▪ Große Medienaufmerksamkeit, gewisse Skepsis am Mehrwert innerhalb der Bevölkerung ▪ Konsortium aus zwei Auftragnehmern (SAP und Deutsche Telekom) ▪ Enger Zeitrahmen ▪ Hoher politischer Druck, viele Parteien involviert (Ministerien, Behörden, RKI) ▪ Hohe Datenschutzanforderungen Technisch ▪ Betrieb in der Cloud ▪ Native mobile Clients ▪ Einsatz des Exposure Notification Framework
31. Einflüsse auf Entscheidungen - schränken die Lösung ein - schließen Optionen aus - prägen die Lösung - nachher schwierig “einzubauen” Qualitätsanforderungen Benutzbarkeit, Effizienz, Wartbarkeit, Sicherheit ... Vorgaben/Rahmenbedingungen Technisch (z.B. Datenbankprodukt) Organisatorisch (z.B. Team)
32. Ziel Beschreibung Höchster Datenschutz Der Schutz der personenbezogenen Daten hat oberste Priorität. (Sicherheit) Effektive Warnfunktionalität Die App ist ein effektiver Baustein bei der Pandemie-Bekämpfung. (Funktionale Eignung) Attraktive Lösung für App- Nutzer Die App ist leicht zu installieren sowie intuitiv und effizient zu bedienen. (Benutzbarkeit) Hohe Zuverlässigkeit Die Lösung geht mit Lastspitzen wegen hoher Nutzer- oder Infektionszahlen ebenso souverän um, wie mit böswilligen Angriffen. (Zuverlässigkeit) Gute Änderbarkeit Die Software lässt sich leicht anpassen, wenn z. B. Nutzer/-innen oder neue Forschungsergebnisse es erfordern. (Wartbarkeit/Erweiterbarkeit) Top-Qualitätsziele Corona-Warn-App Die Reihenfolge gibt Orientierung bezüglich der Wichtigkeit.
33. Architektur- /Lösungsansätze Architektur- /Qualitätsziele Lösungsstrategie Stellt Qualitätsziele und zugeordnete high-level Lösungsansätze in Beziehung zueinander dar. Form: Tabelle ([ Ziele | Lösungsansätze ]).
34. Ziel Passende Lösungsansätze (Auswahl) Höchster Datenschutz • Speicherung der Daten lokal • Verschlüsselung aller Bewegungsdaten • Senden der Daten nur nach Aufforderung • Transparente Entwicklung (Open Source) Effektive Warnfunktionalität • Verwendung Exposure Notification Framework • Digitale Abläufe bevorzugt • Optionales, manuelles Kontakt-Tagebuch Attraktive Lösung für App-Nutzer • Native Clients (L&F) • Übersichtliche Gestaltung und simple Bedienung Hohe Zuverlässigkeit • Microservices • Docker, Kubernetes, Public Cloud • Bereitstellung von zu lesenden Daten über CDN Gute Änderbarkeit • Hoher Modularisierungsgrad • Open Source Projekt, gute Dokumentation • Verwendung von Standard & Open Source Libraries • Konsortium von mehreren Auftragnehmern • Code-Qualität (SonarQube, SwiftLint, Checkstyle, …) Lösungsstrategie Corona-Warn-App
35. „Abheften“ in arc42 ➔https://arc42.de/
36. 39 Kontextsichten Laufzeitsichten Bausteinsichten Verteilungssichten
37. Tatsächliche Zerlegung im Quelltext GitHub-Repositories https://github.com/corona-warn-app/... ▪ cwa-app-android ▪ cwa-app-ios ▪ cwa-server („Backend“) ▪ cwa-testresult-server ▪ cwa-verification-server ▪ cwa-verification-portal „Bausteinsicht, Ebene 1“ CWA-Server (Backend), Bausteinsicht, Ebene 2
38. Zerlegung Backend Server (Bausteinsicht, Ebene 2)
39. „Abheften“ in arc42 ➔https://arc42.de/
40. „Abheften“ in arc42 ➔https://arc42.de/
41. Agenda • Einführung • Architektur dokumentieren • Ein Reifegradmodell • Fazit und Ausblick
42. Docs-as-code / Architecture-as-code
43. Ein Reifegradmodell Dokumentation wird getrennt vom Code verwaltet Es gibt keine Anzeichen des Docs-as-Code Ansatzes
44. 0 -> 1 Dokumentation mit dem Code in Git verwalten Word in Git Wahl einer Auszeichnungssprache
46. Markdown • Markdown • Toller Standard für einfache Auszeichnungen • Features Span Elements Links Emphasis Code Images Block Elements Paragraphs and Line Breaks Headers Blockquotes Lists Code Blocks Horizontal Rules TOC Tables (Feature Rich) Includes (Level-Offset) PlantUML Admonitions Attributes Anchors Footnotes, Index, Glossary Videos Syntax Highlighting Callouts Math Rendering Outputformats
47. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? •CommonMark •CriticMarkup •Discount •DocFX •ExtraMark •Ghost's Markdown/Haunted Markdown •GitHub Flavored Markdown •GitLab Flavored Markdown (with login) •Haroopad Flavored Markdown •iA Writer's Markdown •Kramdown •Leanpub Flavored Markdown •Litedown •Lunamark •Madoko •Markdown •Markdown 2 •Markdown Extra •Markdown-it •Markua •Maruku •MultiMarkdown •Pandoc's Markdown •PHP Markdown Extra Extended •Python Markdown •R Markdown •Redcarpet •Remarkable •Rhythmus •Scholarly Markdown •Showdown •StackOverflow's Markdown •Taiga Markdown •Trello's Markdown •vfmd •Xcode/Swift Playgrounds Markup https://github.com/commonmark/commonmark-spec/wiki/markdown-flavors
48. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? Funktioniert dann unsere Toolchain noch? Haben wir ein Editor-Preview?
49. 64 :::note The content and title *can* include markdown. ::: :::tip You can specify an optional title Heads up! Here's a pro-tip. ::: :::info Useful information. ::: :::caution Warning! You better pay attention! ::: :::danger Danger danger, mayday! ::: ::: tip This is a tip ::: ::: warning This is a warning ::: ::: danger This is a dangerous warning ::: ::: details This is a details block, which does not work in IE / Edge ::: https://v1.vuepress.vuejs.org/guide/markdown.html#custom-containers https://v2.docusaurus.io/docs/2.0.0-alpha.70/markdown-features > [!NOTE] > Information the user should > notice even if skimming. > [!TIP] > Optional information to help > a user be more successful. > [!IMPORTANT] > Essential information required > for user success. > [!CAUTION] > Negative potential consequences > of an action. > [!WARNING] > Dangerous certain consequences > of an action. https://docs.microsoft.com/de-de/contribute/markdown-reference
50. AsciiDoc / Asciidoctor leistungsfähige Syntax für technische Dokumentation in Ruby geschrieben mit Opal nach JavaScript transpiliert mit jRuby auf der JVM gewrapped => Keine Dialekte!
52. asciidoctor your solution architecture documentation read HTML5 generate HTML arc42 asciidoc template is derived from Basic Docs-as-Code with AsciiDoc GIT
53. Ein Reifegradmodell Dokumentation wird in Git mit dem Sourcecode verwaltet
54. 1 -> 2 Maintain Docs like Code? Treat Docs as Code!
55. asciidoctor your solution architecture documentation read HTML5 generate HTML arc42 asciidoc template is derived from Plugins + Scripted Docs-as-Code with AsciiDoc GIT pdf plugin diagram plugin plantUML PDF generate PDF
56. Tabellen!?
57. Tabellen!? CSV
58. Tabellen!? CSV
59. Modulare Dokumentation arc42- master.adoc kapitel1.adoc kapitel2.adoc include include kapitel8.adoc kapitel8.1.adoc public class HelloWorld { public static void main (String[] args) { // Ausgabe Hello World! System.out.println("Hello World!"); } } include include security- master.adoc business- master.adoc
60. Ein Reifegradmodell Dokumentation wird nicht nur als HTML gerendert, sondern auch mit eignen Skripten extrahiert und transformiert. …wie Code
61. Tabellen!? CSV
62. Tabellen!?
63. Zusammenarbeit
64. Zusammenarbeit
65. asciidoctor your solution architecture documentation pdf plugin diagram plugin plantUML read PDF generate PDF HTML5 generate HTML arc42 asciidoc template is derived from Basic Docs-as-Code with AsciiDoc
66. DB Systel GmbH | Ralf D. Müller | @RalfDMueller 81 Basic Docs-as-Code with AsciiDoc & docToolchain
67. Basic Docs-as-Code with AsciiDoc & docToolchain
70. Ein Reifegradmodell Es werden Standard-Skripte zum Extrahieren und Transformieren verwendet, wie z.B. docToolchain
71. Docs-as-Code in der IDE
72. Docs-as-Code in der IDE
73. Docs-as-Code in der IDE
74. Docs-as-Code in der IDE
75. Docs-as-Code in der IDE
76. Docs-as-Code in der IDE
77. Docs-as-Code in der IDE
78. Ein Reifegradmodell Der Docs-as-Code Ansatz wird durch Plugins auch in die IDE getragen Autovervollständigung, Syntax Highlighting, Strukturbrowser, Live-Templates, Code-Folding etc.
79. Agenda • Einführung • Architektur dokumentieren • Ein Reifegradmodell • Fazit und Ausblick
80. Fazit und Ausblick
81. Lust auf mehr Docs-as-Code? Wir bieten Tages-Workshops an. Sprecht uns an! fs@embarc.de
82. ralf.d.mueller@deutschebahn.com @RalfDMueller Vielen Dank. Wir freuen uns auf Eure Fragen! falk.sippach@embarc.de @sippsack