Ralf D. Müller. Docs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz

Transkript

1 Docs-as-Code Docs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz Ralf D.

2 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 2

3 Dr. Gernot Starke innoq Fellow Softwarearchitektur Entwurf Evolution + Modernisierung Dokumentation Reviews

4 Was machen wir die nächsten 50 Minuten? Mischung aus Tipps zu arc42 und docs-like-code Best Practice zum Umgang zur Pflege einer Architekturdokumentation Experimentelle Features :-) Vorschläge aus Erfahrung, keine Silver @doctoolchain 4

5 Das VENOM Projekt VEry NOrMal System Gewachsene Dokumentation Unterschiedliche Stakholder Aufgrund verschiedener Änderungen stets im Wandel Hoher @doctoolchain 5

6 Darf ich vorstellen? Geoff Solution Architect Geoff ist Solution Architect bei SAMM Inc Zuständig für VENOM Starker technischer Background Aufgaben: Weiterentwicklung der Architektur Pflege der Dokumentation Kommunikation der @doctoolchain 6

7 Format der Dokumentation MS Word ist der etablierte Standard Arc42 existiert in vielen Formaten: Docx latex html Asciidoc textile confluence markdown Geoff wählt AsciiDoc aufgrund vieler @doctoolchain 7

8 arc42 Formate AsciiDoc ist aus unserer Sicht das flexibelste Format Da es in alle anderen Formate (fast verlustfrei) gewandelt werden kann, gibt es immer Plan @doctoolchain 8

9 Demo eine erste Konvertierung 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 @doctoolchain 9

10 Demo eine erste Konvertierung demo.adoc build.gradle console output plugins { id "org.asciidoctor.convert" version "1.5.3" @doctoolchain 10

11 Demo eine erste Konvertierung 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: secs PS @doctoolchain 11

12 Demo eine erste Konvertierung build.gradle demo.adoc console output @doctoolchain 12

13 Tools zur Konvertierung Geringste Einstiegshürde: Gradle und asciidoctorj Maven ist aufwändiger, gut unterstützt Gradle bezüglich weiterer Build-Steps flexibler

14 Out-of-the-Box Features ablenkungsfrei Dokumentation wie s schreiben Gliederung in Unterdokumente Neugliederung je nach Stakeholder Bilder werden referenziert, nicht eingebettet leichte Versionierung handle Docs-as-Code Formatierung von Source-Code Reviews, Pull-Requests, Versionierung durch Git Konvertierung nach HTML5 und @doctoolchain 14

15 doch die Reise beginnt erst Geoff ist mit seiner Entscheidung erst mal zufrieden die alte Dokumentation muss aber zunächst überführt werden.docx.adoc.adoc.html.adoc Geoff entscheidet sich im Rahmen einer Überarbeitung die Dokumentation per Copy & Paste in AsciiDoc zu @doctoolchain 16

16 treat Docs-as-Code Geoff erkennt, dass die Transformation nach AsciiDoc erst der Anfang war Als nächstes möchte er durch den Docs-as-Code Ansatz die Überarbeitung der Dokumentation weiter @doctoolchain 17

17 treat Docs-as-Code I: Version @doctoolchain 18

18 treat Docs-as-Code II: Git-Flow Fork @doctoolchain 19

19 treat Docs-as-Code III: Build-Server Fork PR On Change Build- Server @doctoolchain 20

20 Diagramme Geoff stört sich weiterhin an dem hohen Pflegeaufwand für Diagramme Beherrscht AsciiDoc nicht @doctoolchain 21

21 Diagramme: @doctoolchain 22

22 Diagramme: PlantUML.Benutzer und Benutzergruppen von VENOM [plantuml] ----!pragma graphviz_dot jdot :Private User: as private :User Groups: as groups :Corporate Users: as corporate :Government Users: as gov :Regulation &\nstandard Bodies: as bodies :Operations: as ops :internal Users: as internal (VENOM\ni.B.O.S.S) as venom private -right-> venom groups --> venom corporate --> venom gov -up-> venom bodies -up-> venom ops --> venom internal -left-> venom @doctoolchain 23

23 Diagramme: PlantUML Komplexe Diagramme als einfachen Text verwalten Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet. Sequenzdiagramme sind jedoch ein sehr guter @doctoolchain 24

24 Diagramme Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen Noch keinen eigenen Stil gefunden? => C4 von Simon Brown ist ein guter Start @doctoolchain 26

25 Diagramme: Modellierung Geoff pflegt seine Architektur in einem UML- Modellierungstool Das Einbetten der Grafiken in die Dokumentation ist jedoch schwerfällig Des weiteren macht Geoff sich auch gerne Notizen im UML-Modell, welche dann in der Dokumentation @doctoolchain 27

26 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 @doctoolchain 28

27 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 @doctoolchain 29

28 treat Docs-as-Code IV: automate === 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[] @doctoolchain 30

29 treat Docs-as-Code IV: @doctoolchain 31

30 Stakeholder Geoff bemerkt schnell, dass nicht jeder mit einer online HTML-Dokumentation glücklich ist Er muss für unterschiedliche Stakeholder die Dokumente auch unterschiedlich aufbereiten

31 .docx bzw. MS Word

32 .docx bzw. MS Word

33 ...bzw. pdf

34 Zusammenarbeit Aber alle anderen Dokumente sind in Confluence Confluence speichert die Seiten intern als xhtml und hat eine REST-API et @doctoolchain 36

35 @doctoolchain 37

36 @doctoolchain 38

37 @doctoolchain 39

38 @doctoolchain 40

39 @doctoolchain 41

40 Broken Links Geoff fällt auf, dass er immer wieder mit Probleme mit Tippfehlern in Dateinamen oder Verlinkungen im Dokument hat Wie löst man solche Probleme mit Code? => natürlich mit automatisierten @doctoolchain 42

41 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 @doctoolchain 43

42 Automatisiertes Testing der Doku @doctoolchain 44

43 demnächst: Linting @doctoolchain 45

44 Bonus: Export PPT Sprechernotizen enthalten asciidoc Slides und asciidoc werden automatisch exportiert

45 Bonus: Export PPT

46 @doctoolchain 48

47 Fragen? Antworten! Clipart: presentermedia.com, licenced @doctoolchain 49