Softwarearchitektur kontinuierlich und effizient dokumentieren

Transkript

1 Softwarearchitektur kontinuierlich und effizient dokumentieren Orientation in Objects GmbH Weinheimer Str Mannheim Version: Ihre Sprecher Falk Sippach Trainer, Berater, Entwickler Co-Organisator Architektur Agile Softwareentwicklung Codequalität Commiter DukeCon 2 1

2 Zusammenschluss Trivadis und OIO Im Mai diesen Jahres haben sich Trivadis und Orientation in Objects (OIO) zusammengeschlossen. Gemeinsam stärken und erweitern wir unser Angebot im Bereich Java und agiler Softwareentwicklung. Gemeinsam bieten wir ein zwölfmonatiges Trainee- Programm an, das Experten für Java- und Webtechnologien ausbildet. Neu finden Sie im Trivadis Trainingsangebot auch Kurse, die von der OIO entwickelt und durchgeführt werden. Abstract Man kann zwar an vielen Stellen nachlesen, wie man Architekturdokumentation strukturiert. Aber auf der Suche nach einer praktikablen Handhabung zur Erstellung und Pflege enden die meisten Versuche in der WYSIWYG-Hölle einer Textverarbeitung oder im tiefen Schlund eines Wikis. In diesem Vortrag wollen wir uns anschauen, wie aufbauend auf bestehenden Tools und Textformaten eine möglichst redundanzfreie Dokumentation erstellt und für verschiedene Zielgruppen in ansprechenden Formaten ausgeliefert werden kann. Es wird dabei um Begriffe wie Continuous Documentation und Documentation as Code gehen. 4 2

3 Doku-Smells Die7 Sündender Architekturdokumentation Foto von jesperbkskov: (CC0 Public Domain Lizenz) 5 Anforderungen klären Warum dokumentieren? Architektur bewerten Architektur kommunizieren Architektur entwerfen aus: Effektive Softwarearchitekturen (G. Starke) 6 3

4 Gründe für eine Architektur-Dokumentation Entwurfsunterstützung Kommunikation Bewertbarkeit Frage nach Warum Neue Mitarbeiter Grafik von The Practical Dev: (CC0 Public Domain Lizenz) 7 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 8 4

5 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 9 Hauptsache, du machst es nicht mit Word!

6 Textverarbeitung Visio Powerpoint UML-Tools Foto von Antranias: (CC0 Public Domain Lizenz) 11 Alternative Datenformate zu Textverarbeitung Plain-Text, leicht lesbar, einfach editierbar, automatisiert verarbeitbar Plain-Text Wikis kollaborativ visuell, kurz & knapp Mindmaps LaTex/DocBook Austauschformat eingeschränkte Lesbarkeit Richtext 12 6

7 Markdown Normaler Text wird so dargestellt wie eingegeben. *Kursiv*, **Fett** und ***Fett kursiv*** bzw. _Kursiv_, Fett und Fett kursiv Markiert Text als `Inline-Quelltext` Ein Code-Block durch Einrückung mit vier Leerzeichen * Ein Punkt in einer ungeordneten Liste * Ein Unterpunkt, um vier Leerzeichen eingerückt 1. Ein Punkt in einer geordneten Liste 2. Ein weiterer Punkt 1. Noch ein Punkt bei mehrfacher Angabe derselben Ziffer # Überschrift in Ebene 1 #### Überschrift in Ebene 4 13 AsciiDoc 14 7

8 Welcher Markup-Typ bin ich? 15 Templates für: Microsoft Word Confluence Markdown, AsciiDoc Latex, DocBook HTML, EPUB Textile 16 8

9 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 17 Foto von UliSchu: (CC0 Public Domain Lizenz) 18 9

10 Unser täglich Entwickler-Brot: Plain-Text Entwicklungsumgebung Kommandozeilenwerkzeuge Versionsverwaltung Foto von geralt: (CC0 Public Domain Lizenz) 19 Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate Documentation as Code Foto von ahobbit: (CC0 Public Domain Lizenz) 20 10

11 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 21 Single Source of Truth Includes Quellcode verlinken Platzhalter einbetten Foto von pcdazero: (CC0 Public Domain Lizenz) 22 11

12 Inhalte generieren WSDL, Swagger DB-Schema Annotationen JavaDoc Markup generieren Foto von ClassicallyPrinted: (CC0 Public Domain Lizenz) 23 Schnittstellenbeschreibung generieren 24 12

13 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 25 Ein Bild sagt mehr als tausend Worte! 26 13

14 Quelle für Bilder/Grafiken im Binärformat Export aus UML-Modellen Manuelle Erstellung (Bildverarbeitung/Visualisierungsprogramme) Einbetten/Verlinken in Markup-Sprachen: image::bild.png[alternativtext] 27 Tools yed ist ein kostenloses Visualisierungsprogramm und Visio, Enterprise Architect, Magic Draw, 28 14

15 Diagramme als textuelle Beschreibung 29 "AsciiArt" 30 15

16 Online- Tools 31 Generation Plain-Text-Diagramme Quellen: Sourcecode DB-Schema XML-Modell Foto von herbert2512: (CC0 Public Domain Lizenz) 32 16

17 Quellcode DB-Schema UML-Modell Schnittstellen Konfiguration interface DemoService { String foobar(); } class DemoServiceImpl implements DemoService public String foobar() { return "demo"; } } enum State { NEW, OPEN, APPROVED, IN_PROGRESS, FIXED } PlantUML + AsciiDoc interface DemoService DemoService < -- DemoServiceImpl enum State { NEW OPEN APPROVED IN_PROGRESS FIXED # Werte von State * NEW * OPEN * APPROVED * IN_PROGRESS * FIXED 33 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 34 17

18 Agile Projekte iterativ kontinuierlich Foto von Unsplash: (CC0 Public Domain Lizenz) 35 Automatisiert erstellen Regelmässig ausliefern Ständig ergänzen Reviewen Nachbessern Continuous Documentation Foto von Ted Van Pelt: (CC BY 2.0 Lizenz) 36 18

19 HTML, PDF, Entwickler Dokumentation als Plain Text Leser 37 Ausrichtung auf Zielgruppen und Ausgabeformate 38 19

20 Single Source of Truth Blog/Wiki Präsentation Dokument Video, Podcast PDF HTML E-Reader Papier Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 40 20

21 41 Wenn man die Architektur nicht erklären/dokumentieren kann, ist sie zu kompliziert! 42 21

22 nur so viel wie nötig geringe Änderungsrate Zielgruppenbedürfnisse Feedback einpflegen Pragmatik/Effektivität Foto von PublicDomainPictures: (CC0 Public Domain Lizenz) Foto von Devanath: (CC0 Public Domain Lizenz) 43 Validierung SanityChecks Broken Links PDFUnit Foto von skeeze: (CC0 Public Domain Lizenz) 44 22

23 Ausführbare Dokumentation Ausführbare Tests Einbettung in Dokument Reportgenerierung Foto von Wikimedia: ( Creative Commons Attribution 3.0 Unported)

24 Kontinuierliche Analyse der Architekturkonformität Quellcode Artefakte Report Regeln (Soll-Architektur) Veröffentlichung (SonarQube)

25 Living Documentation + 49 PlantUML AsciiDoc [[architecture:defineddependencies] [plantuml,role=concept] ---- [artifactid:xo.impl] as impl <<:Maven:Project>> [artifactid:xo.api] as api <<:Maven:Project>> [artifactid:xo.spi] as spi <<:Maven:Project>> [[architecture:undefineddependencies]] [source,cypher,role=constraint,requiresconcepts="archit There must not be dependencies between Maven projec ---- MATCH (p1:maven:project)-[:creates]->(:artifact)-[:contain (p2:maven:project)-[:creates]->(:artifact)-[:contain (t2)-[:depends_on]->(t1) WHERE NOT (p1)-[:defines_dependency]->(p2) RETURN * ---- impl -> api : Defines Dependency impl -> spi : Defines Dependency spi -> api : Defines Dependency

26 Softwarearchitekturvisualisierung coden 51 Doku-Smells WYSIWYG ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 52 26

27 Klassische Architekten Rolle Foto von scottwebb: (CC0 Public Domain Lizenz) 53 Architekt/Senior Developer als Ratgeber/Mentor und Moderator Foto von JESHOOTS: (CC0 Public Domain Lizenz) 54 27

28 Vorbereiten Planen Erinnern Delegieren Integrieren Prüfen Dokumentation braucht einen Kümmerer Foto von Berzin: (CC0 Public Domain Lizenz) 55 WYSIWYG Doku-Smells ABLAGE REDUNDANZEN TEXTWÜSTE HANDARBEIT TOTE DOKU ELFENBEINTURM 56 28

29 Zusammenfassung WYSIWYG Plain Text ABLAGE Documentation as Code REDUNDANZEN Generierung TEXTWÜSTE Mehr Grafiken HANDARBEIT Automatisierung TOTE DOKU Lebendige Dokument. ELFENBEINTURM Kümmerer 57 REPO Continuous Documentation Documentation as Code 58 29

30 Vielen Dank für Ihre Aufmerksamkeit! Orientation in Objects GmbH Weinheimer Str Mannheim 59 Verschiedene Szenarien Foto von nikidinov: (CC0 Public Domain Lizenz) 60 30

31 Szenario 1: Markdown, Pandoc, PlantUML, yed Schreiben in Markdown in IDE (IntelliJ IDEA) inkl. Preview PDF-Erzeugung mit PanDoc über LaTex-Zwischenschritt inkl. Corporate Design UML-Diagramme mit PlantUML, Live-Ansicht/Export aus IDE andere Diagramme mit yed, Export als *.png Stash/Bitbucket Server als Repo rendert Markdown direkt in Weboberfläche readme.md Verlinkungen auf wichtige Dokumente 61 Szenario 2: AsciiDoctor, Maven, PlantUML Erstellen AsciiDoc und PlantUML in IDE mit Preview Maven-Plugin zum Erzeugen des HTML/PDF 62 31

32 Szenario 3: Generierung aus Quellcode Quellcode parsen Reflection Spring Kontext in Unit-Test aus Klassen-Strukturen Diagramm-Markup erzeugen z. B. PlantUML als Text-Datei ablegen und in Markup-Dokumentation verlinken im Build-Prozess als Input für Markup-Konvertierung einlesen 63 Szenario 4: Schnittstellenbeschreibung Generierung aus WSDL, WADL, Swagger Einbindung in Build-Prozess Swagger2Markup JAX-RS Analyzer Spring REST Docs 64 32

33 Szenario 5: Ausführbare Dokumentation Quellcode-Struktur in Graph-Datenbank importieren Architektur-Regeln als Graph-Abfragen in AsciiDoc einbetten 65 Szenario 6: doctoolchain doctoolchainis an implementation of thedocs-as-code approach for software architecture. The basis of doctoolchain is the philosophy that software documentation should be treated in the same way as code together with the arc42 template for software architecture

34 Szenario 7: Wiki CC BY-SA 3.0, 67 Zusammenarbeit Verlinkung Review-/Redaktions-Prozess Prozess-Unterstützung Abbildung Workflow Erweiterung über Plugins Alles in einer Box! Foto von makamuki0: (CC0 Public Domain Lizenz) 68 34

35 Strukturiert? Plain-Text? Offlinefähigkeit? Versionierung? Code-Nähe? Automatisierung? Druckausgabe? Zielgruppen? Kontextwechsel Schlund des Wiki Foto von MartinStr: (CC0 Public Domain Lizenz) 69 Tasks Mentions Kommentare Jira 70 35

36 Gliffy (Diagramme, UML) Balsamiq Mockups 71 36