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

Moderne Softwarearchitekturen dokumentieren und kommunizieren

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.

Ralf D. Müller

October 05, 2021
Tweet

More Decks by Ralf D. Müller

Other Decks in Programming

Transcript

  1. [email protected] @sippsack ➔ xing.to/fsi Falk Sippach ◼ Softwarearchitekt, Berater, Trainer

    bei embarc ◼ früher bei Orientation in Objects (OIO), Trivadis
  2. [email protected] @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
  3. 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
  4. 10 aus: Effektive Softwarearchitekturen (G. Starke) Architektur bewerten Architektur kommunizieren

    Architektur entwerfen Anforderungen klären Architektur kommunizieren
  5. 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)
  6. Documentation-as-Code Ablage im Repo Versionier- /Diffbar Synchrone Auslieferung Offlinefähig Teil

    des Build- Prozesses Generierung/ Automatisierung Flexible Ausgabe Nähe zum Sourcecode
  7. 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
  8. 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
  9. 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
  10. 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
  11. 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/
  12. 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:
  13. 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 ...
  14. 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
  15. Einflüsse auf Entscheidungen - schränken die Lösung ein - schließen

    Optionen aus Vorgaben/Rahmenbedingungen Technisch (z.B. Datenbankprodukt) Organisatorisch (z.B. Team)
  16. 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
  17. 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)
  18. 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.
  19. 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 ]).
  20. 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
  21. 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
  22. 0 -> 1 Dokumentation mit dem Code in Git verwalten

    Word in Git Wahl einer Auszeichnungssprache
  23. 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
  24. 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
  25. Markdown Wir brauchen eine Erweiterung! Welche wählen wir? Funktioniert dann

    unsere Toolchain noch? Haben wir ein Editor-Preview?
  26. 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
  27. 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!
  28. asciidoctor your solution architecture documentation read HTML5 generate HTML arc42

    asciidoc template is derived from Basic Docs-as-Code with AsciiDoc GIT
  29. 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
  30. 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
  31. Ein Reifegradmodell Dokumentation wird nicht nur als HTML gerendert, sondern

    auch mit eignen Skripten extrahiert und transformiert. …wie Code
  32. 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
  33. DB Systel GmbH | Ralf D. Müller | @RalfDMueller 81

    Basic Docs-as-Code with AsciiDoc & docToolchain
  34. 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.