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.

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

October 05, 2021
Tweet

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
  4. None
  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
  23. None
  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
  45. None
  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!
  51. None
  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

  68. None
  69. None
  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