Docs-as-Code - Architekturdokumentation leicht gemacht

Slide 1

Slide 1 text

Docs-as-Code Architekturdokumentation leicht gemacht Ralf D. Müller, Falk Sippach @docToolchain

Slide 2

Slide 2 text

Ralf D. Müller Bei Tag Solution Architect in der Digital Factory der Deutschen Bank. In der Freizeit Geek mit Schwerpunkt Web-Technologien Qualität (Security, Testautomation) Produktivität (Gradle, Groovy, Grails) Maintainer von docToolchain 26.04.2018 @RalfDMueller @sippsack @docToolchain 2

Slide 3

Slide 3 text

Falk Sippach Orientation in Objects GmbH Trainer, Berater, Entwickler in Mannheim. JUG Darmstadt Co-Organisator Committer DukeCon Konferenzplaner 26.04.2018 @RalfDMueller @sippsack @docToolchain 3

Slide 4

Slide 4 text

Was machen wir die nächsten 50 Minuten? Was ist docs-as-code? Warum docs-as-code? Wie kann docs-as-code umgesetzt werden? Experimentelle Features :-) Vorschläge aus Erfahrung, keine Silver Bullet 26.04.2018 @RalfDMueller @sippsack @docToolchain 4

Slide 5

Slide 5 text

Architektur dokumentieren? 26.04.2018 @RalfDMueller @sippsack @docToolchain 5 Anforderungen klären Architektur entwerfen Architektur bewerten aus: Effektive Softwarearchitekturen (G. Starke + P. Hruschka) Architektur kommunizieren

Slide 6

Slide 6 text

Warum dokumentieren? 26.04.2018 @RalfDMueller @sippsack @docToolchain 6 Grafik von The Practical Dev: https://github.com/thepracticaldev/orly-full-res/blob/master/notwritingdocs-big.png (CC0 Public Domain Lizenz) Entwurfsunterstützung Kommunikation Bewertbarkeit Frage nach Warum Neue Mitarbeiter

Slide 7

Slide 7 text

Dokumentieren nervt! Falsche Werkzeuge (WYSIWYG) Dateiablage im Share-Laufwerk Redundanzen Textwüste Handarbeit Veraltet Liest sowieso keiner! 26.04.2018 @RalfDMueller @sippsack @docToolchain 7

Slide 8

Slide 8 text

26.04.2018 @RalfDMueller @sippsack @docToolchain 8 Hauptsache, du machst es nicht mit Word!

Slide 9

Slide 9 text

WYSIWYG Tools 26.04.2018 @RalfDMueller @sippsack @docToolchain 9 Foto von Antranias: https://pixabay.com/en/telescope-view-distant-binoculars-1201497/ (CC0 Public Domain Lizenz) Textverarbeitung Visio Powerpoint UML-Tools

Slide 10

Slide 10 text

Leichtgewichtige Textformate Plain-Text (Markdown, AsciiDoc) LaTex/DocBook Wiki Mindmaps Richtext 26.04.2018 @RalfDMueller @sippsack @docToolchain 10

Slide 11

Slide 11 text

Ein Bild sagt mehr als 1000 Worte … 26.04.2018 @RalfDMueller @sippsack @docToolchain 11 Erstellen mit Grafik-Tools • yEd, UML-Tools, … • Einbetten in Markup Erstellen in Textformaten • PlantUML, ditaa, …

Slide 12

Slide 12 text

Dateiablage 26.04.2018 @RalfDMueller @sippsack @docToolchain 12 Foto von UliSchu: https://pixabay.com/en/organization-register-folder-files-1205171/ (CC0 Public Domain Lizenz)

Slide 13

Slide 13 text

Unser täglich Brot … 26.04.2018 @RalfDMueller @sippsack @docToolchain 13 Foto von geralt: https://pixabay.com/de/unternehmer-start-start-up-karriere-696976/ (CC0 Public Domain Lizenz) Plain-Text Texteditor/IDE Kommandozeile Buildwerkzeuge Versionsverwaltung

Slide 14

Slide 14 text

Documentation as Code 26.04.2018 @RalfDMueller @sippsack @docToolchain 14 Foto von ahobbit: https://pixabay.com/en/vault-business-bank-vault-bank-1144249/ (CC0 Public Domain Lizenz) Code-Nähe Ablage im Repo Versionier-/diffbar Synchrone Auslieferung Offlinefähig Teil des Build-Prozess Generierung Automatisierung Flexible Ausgabeformate

Slide 15

Slide 15 text

Redundanzen vermeiden 26.04.2018 @RalfDMueller @sippsack @docToolchain 15 Foto von pcdazero: https://pixabay.com/en/umbrellas-sea-holiday-summer-beach-921501/ (CC0 Public Domain Lizenz) Includes Quellcode verlinken Platzhalter einbetten Inhalte generieren: • WSDL, Swagger DB-Schema Annotationen JavaDoc Markup generieren

Slide 16

Slide 16 text

Continuous Documentation 26.04.2018 @RalfDMueller @sippsack @docToolchain 16 Foto von Ted Van Pelt: https://www.flickr.com/photos/bantam10/5209157298 (CC BY 2.0 Lizenz) Agile Projekte: • iterativ • kontinuierlich Dokumentation: • automatisiert erstellen • regelmässig ergänzen • reviewen, nachbessern

Slide 17

Slide 17 text

Die Wahl der Sprache 26.04.2018 @RalfDMueller @sippsack @docToolchain 17 Markdown, textile reStructuredText AsciiDoc(tor)

Slide 18

Slide 18 text

demo.adoc build.gradle console output = A first Headline And a first paragraph. It continous on the next headline Second paragraph. == Second-Level Headline A link to http://asciidoctor.org/docs[Asciidoctor.org] Demo – eine erste Konvertierung 26.04.2018 @RalfDMueller @sippsack @docToolchain 18

Slide 19

Slide 19 text

demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" } Demo – eine erste Konvertierung 26.04.2018 @RalfDMueller @sippsack @docToolchain 19

Slide 20

Slide 20 text

build.gradle demo.adoc console output PS C:\Users\Demo\jax2017\demo1> gradle asciidoc :asciidoctor io/console not supported; tty will not be manipulated BUILD SUCCESSFUL Total time: 4.554 secs PS C:\Users\Demo\jax2017\demo1> Demo – eine erste Konvertierung 26.04.2018 @RalfDMueller @sippsack @docToolchain 20

Slide 21

Slide 21 text

build.gradle demo.adoc console output Demo – eine erste Konvertierung http://asciidoctor.org/docs/render-documents/ 26.04.2018 @RalfDMueller @sippsack @docToolchain 21

Slide 22

Slide 22 text

Out-of-the-Box Features „ablenkungsfrei“ – Dokumentation wie eMails schreiben Gliederung in Unterdokumente Neugliederung je nach Stakeholder Bilder werden referenziert, nicht eingebettet leichte Versionierung „treat Docs-as-Code“ Formatierung von Source-Code Reviews, Pull-Requests, Versionierung durch Git Konvertierung nach HTML5 und DocBook 26.04.2018 @RalfDMueller @sippsack @docToolchain 22

Slide 23

Slide 23 text

Scaffolding 26.04.2018 @RalfDMueller @sippsack @docToolchain 23 Guides

Slide 24

Slide 24 text

arc42 … 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 24 … ist das Standard-Template im deutschsprachigen Raum … ist verfügbar in Deutsch, Englisch und Spanisch … is verfügbar in 9 Formaten (.adoc, .docx, .rst, .md, .tex …) … gibt Ihrer Architekturdokumentation eine Structure … ist verfügbar mit und ohne Hilfe

Slide 25

Slide 25 text

arc42 – eher Kleiderschrank als Formular 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 25

Slide 26

Slide 26 text

arc42 – eher Kleiderschrank als Formular 1. Requirements & Goals 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 26 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

Slide 27

Slide 27 text

arc42 als AsciiDoc Template 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 27 == Architecture Constraints [role="arc42help"] **** .Contents Any requirement that constrains software architects in their freedom of design and implementation decisions or decision about the development process. These constraints sometimes go beyond individual systems and are valid for whole organizations and companies. .Motivation Architects should know exactly where they are free in their design decisions and where they must adhere to constraints. Constraints must always be dealt with; they may be negotiable, though. .Form Simple tables of constraints with explanations. If needed you can subdivide them into technical constraints, organizational and political constraints and conventions (e.g. programming or versioning guidelines, documentation or naming conventions) ****

Slide 28

Slide 28 text

treat Docs-as-Code I: Version Control .adoc .adoc .adoc .html 26.04.2018 @RalfDMueller @sippsack @docToolchain 28

Slide 29

Slide 29 text

treat Docs-as-Code II: Git-Flow .adoc .adoc .adoc .html Fork PR .adoc 26.04.2018 @RalfDMueller @sippsack @docToolchain 29

Slide 30

Slide 30 text

treat Docs-as-Code III: Build-Server .adoc .adoc .adoc .html Fork PR .adoc Build- Server On Change Publish 26.04.2018 @RalfDMueller @sippsack @docToolchain 30

Slide 31

Slide 31 text

Diagramme 26.04.2018 @RalfDMueller @sippsack @docToolchain 31

Slide 32

Slide 32 text

Diagramme: PlantUML http://plantuml.com/ http://asciidoctor.org/docs/asciidoctor-diagram/ Komplexe Diagramme als einfachen Text verwalten 26.04.2018 @RalfDMueller @sippsack @docToolchain 32

Slide 33

Slide 33 text

Diagramme: PlantUML 26.04.2018 @RalfDMueller @sippsack @docToolchain 33

Slide 34

Slide 34 text

Diagramme: PlantUML .Benutzer und Benutzergruppen von VENOM [plantuml] ---- !pragma graphviz_dot jdot (VENOM\ni.B.O.S.S) as venom "Private User" -right-> venom "User Groups" --> venom "Corporate Users" --> venom "Government Users" -up-> venom "Regulation &\nStandard Bodies" -up-> venom "Operations" --> venom "Internal Users" -left-> venom ---- 26.04.2018 @RalfDMueller @sippsack @docToolchain 34

Slide 35

Slide 35 text

PlantUML Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet. Sequenzdiagramme sind jedoch ein sehr guter Anwendungsfall! 26.04.2018 @RalfDMueller @sippsack @docToolchain 35

Slide 36

Slide 36 text

Diagrams: PlantUML 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 36

Slide 37

Slide 37 text

Diagrams: PlantUML 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 37

Slide 38

Slide 38 text

PlantUML $ java -jar plantuml.jar -metadata activity.png 26.04.2018 @RalfDMueller @sippsack @docToolchain 38 http://mrhaki.blogspot.de/search/label/PlantUML

Slide 39

Slide 39 text

Diagramme: Modellierung 26.04.2018 @RalfDMueller @sippsack @docToolchain 39

Slide 40

Slide 40 text

treat Docs-as-Code IV: automate Betreiber und Administratoren von VENOM Flexibilität hinsichtlich Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring. 26.04.2018 @RalfDMueller @sippsack @docToolchain 40

Slide 41

Slide 41 text

treat Docs-as-Code IV: automate {adoc:stakeholder} | Operations | Betreiber und Administratoren von VENOM | Flexibilität hinsichtlich Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring. 26.04.2018 @RalfDMueller @sippsack @docToolchain 41

Slide 42

Slide 42 text

=== Stakeholder ==== Benutzer und Benutzergruppen [[figure-users]] image::ea/1.5_Stakeholder.png[title="Benutzer und Benutzergruppen von VENOM"] [cols="2,3,3,2" options="header"] .Benutzer und Benutzergruppen |=== | Rolle | Beschreibung | Ziel | Bemerkungen include::../../ea/stakeholder.ad[] |=== treat Docs-as-Code IV: automate 26.04.2018 @RalfDMueller @sippsack @docToolchain 42

Slide 43

Slide 43 text

treat Docs-as-Code IV: automate 26.04.2018 @RalfDMueller @sippsack @docToolchain 43

Slide 44

Slide 44 text

Diagramme Noch keinen eigenen Stil gefunden? => C4 von Simon Brown ist ein guter Start https://c4model.com/ Context, Containers, Components, Classes 26.04.2018 @RalfDMueller @sippsack @docToolchain 44

Slide 45

Slide 45 text

Stakeholder 26.04.2018 @RalfDMueller @sippsack @docToolchain 45

Slide 46

Slide 46 text

.docx bzw. MS Word http://pandoc.org 26.04.2018 @RalfDMueller @sippsack @docToolchain 46

Slide 47

Slide 47 text

.docx bzw. MS Word 26.04.2018 @RalfDMueller @sippsack @docToolchain 47 .docx bzw. MS Word oder PDF via PDF-Plugin…

Slide 48

Slide 48 text

Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 48

Slide 49

Slide 49 text

Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 49

Slide 50

Slide 50 text

Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 50

Slide 51

Slide 51 text

Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 51

Slide 52

Slide 52 text

Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 52

Slide 53

Slide 53 text

Zusammenarbeit 26.04.2018 @RalfDMueller @sippsack @docToolchain 53

Slide 54

Slide 54 text

Managing Tables in AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 54 [options="header",cols="7,23,17,33,11,11"] |=== | Nr. | Name | Rolle | Email | Telefon | PLZ | 1 | Hubert Kleinschmidt | Product Owner | h.kleinschmidt@example.com | 555 102 | 40388 | 2 | Erika Mustermann | Scrum Master | e.mustermann@example.com | 555 103 | 41222 |=== with MS Excel

Slide 55

Slide 55 text

Managing Tables in AsciiDoc 17.03.2018 @RalfDMueller @arc42Tipps @docToolchain 55

Slide 56

Slide 56 text

Testing 26.04.2018 @RalfDMueller @sippsack @docToolchain 56

Slide 57

Slide 57 text

Automatisiertes Testing der Doku Broken Cross References (aka Broken Internal Links) Missing Images Files Multiple Definitions of Bookmarks or ID’s Missing Local Resources Missing Alt-tags in Images https://github.com/aim42/htmlSanityCheck 26.04.2018 @RalfDMueller @sippsack @docToolchain 57

Slide 58

Slide 58 text

Automatisiertes Testing der Doku https://github.com/aim42/htmlSanityCheck 26.04.2018 @RalfDMueller @sippsack @docToolchain 58

Slide 59

Slide 59 text

… demnächst: Linting 26.04.2018 @RalfDMueller @sippsack @docToolchain 59 http://www.hemingwayapp.com/ https://github.com/btford/write-good

Slide 60

Slide 60 text

Bonus: Export PPT ▪Sprechernotizen enthalten asciidoc ▪Slides und asciidoc werden automatisch exportiert 26.04.2018 @RalfDMueller @sippsack @docToolchain 60

Slide 61

Slide 61 text

Bonus: Export PPT 26.04.2018 @RalfDMueller @sippsack @docToolchain 61

Slide 62

Slide 62 text

Ausführbare Dokumentation 26.04.2018 @RalfDMueller @sippsack @docToolchain 62

Slide 63

Slide 63 text

jQAssistant: Regeln in AsciiDoc 26.04.2018 @RalfDMueller @sippsack @docToolchain 63 j

Slide 64

Slide 64 text

Living Documentation 26.04.2018 @RalfDMueller @sippsack @docToolchain 64

Slide 65

Slide 65 text

PlantUML zu jQAssistant-Regel 26.04.2018 @RalfDMueller @sippsack @docToolchain 65 Architektur- definition in PlantUML Generierte Cypher- Regel [[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>> impl -> api : Defines Dependency impl -> spi : Defines Dependency spi -> api : Defines Dependency ---- [[architecture:UndefinedDependenci [source,cypher,role=constraint,requir There must not be dependencies bet ---- MATCH (p1:Maven:Project)-[:CREATES]->(:A (p2:Maven:Project)-[:CREATES]->(:A (t2)-[:DEPENDS_ON]->(t1) WHERE NOT (p1)-[:DEFINES_DEPENDENCY]->(p2 RETURN * ----

Slide 66

Slide 66 text

docToolchain 26.04.2018 @RalfDMueller @sippsack @docToolchain 66

Slide 67

Slide 67 text

Fragen? Antworten! 26.04.2018 @RalfDMueller @sippsack @docToolchain 67 https://doctoolchain.github.io https://jaxenter.de/tag/hhgdc https://docs-as-co.de https://arc42.org Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com Ralf.D.Mueller@gmail.com @RalfDMueller https://rdmueller.github.io @docToolchain falk.sippach@oio.de @sippsack https://www.jug-da.de/