Upload
truongnguyet
View
217
Download
0
Embed Size (px)
Citation preview
Docs-as-CodeDocs-as-Code: arc42, AsciiDoc, Gradle & Co. im Einsatz
Ralf D. Müller
@docToolchain
Ralf D. Müller
Bei Tag Solution Architectin 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
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 2
Dr. Gernot StarkeinnoQ Fellow
Softwarearchitektur ▪ Entwurf▪ Evolution + Modernisierung ▪ Dokumentation ▪ Reviews
Was machen wir die nächsten 50 Minuten?
Mischung aus Tipps zu arc42und docs-like-code
Best Practice zum Umgang zur Pflege einer Architekturdokumentation
Experimentelle Features :-)
Vorschläge aus Erfahrung, keine Silver Bullet
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 4
Das VENOM Projekt
VEry NOrMal System
Gewachsene Dokumentation
Unterschiedliche Stakholder
Aufgrund verschiedener Änderungen stets im Wandel
Hoher Pflegeaufwand
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 5
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 Architektur
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 6
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 Vorteile
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 7
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 B“
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 8
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
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 9
demo.adoc build.gradle console output
plugins { id "org.asciidoctor.convert" version "1.5.3" }
Demo – eine erste Konvertierung
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 10
build.gradle demo.adoc console output
PS C:\Users\Demo\jax2017\demo1> gradle asciidoc:asciidoctorio/console not supported; tty will not be manipulated
BUILD SUCCESSFUL
Total time: 4.554 secsPS C:\Users\Demo\jax2017\demo1>
Demo – eine erste Konvertierung
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 11
build.gradle demo.adoc console output
Demo – eine erste Konvertierung
http://asciidoctor.org/docs/render-documents/
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 12
Tools zur Konvertierung
Geringste Einstiegshürde: Gradle und asciidoctorj
Maven ist aufwändiger, gut unterstützt
Gradle bezüglich weiterer Build-Steps flexibler
Out-of-the-Box Features
„ablenkungsfrei“ – Dokumentation wie eMails 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 DocBook
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 14
.adoc.adoc
…doch die Reise beginnt erst
Geoff ist mit seiner Entscheidung erst mal zufrieden
die alte Dokumentation muss aber zunächst überführt werden
Geoff entscheidet sich im Rahmen einer Überarbeitung die Dokumentation per Copy & Paste in AsciiDoc zu überführen.
.docx .adoc .html
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 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 vereinfachen
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 17
treat Docs-as-Code I: Version Control
.adoc.adoc.adoc .html
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 18
treat Docs-as-Code II: Git-Flow
.adoc.adoc.adoc .html
Fork
PR
.adoc
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 19
treat Docs-as-Code III: Build-Server
.adoc.adoc.adoc .html
Fork
PR
.adoc
Build-Server
On Change
Publish
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 20
Diagramme
Geoff stört sich weiterhin an dem hohen Pflegeaufwand für Diagramme
Beherrscht AsciiDoc nicht PlantUML?
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 21
Diagramme: PlantUML
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 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 venomprivate -right-> venomgroups --> venomcorporate --> venomgov -up-> venombodies -up-> venomops --> venominternal -left-> venom----
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 23
Diagramme: PlantUML
http://plantuml.com/
http://asciidoctor.org/docs/asciidoctor-diagram/
Komplexe Diagramme als einfachen Text verwalten
Nicht alle Diagrammtypen sind für PlantUML gleichgut geeignet.Sequenzdiagramme sind jedoch ein sehr guter Anwendungsfall!
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 24
Diagramme
Im Zweifel Pfeile immer vom Aufrufenden zum Aufgerufenen
Noch keinen eigenen Stil gefunden?=> C4 von Simon Brown ist ein guter Starthttp://www.codingthearchitecture.com/2014/08/24/c4_model_poster.html
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 26
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 fehlen
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 27
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.
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 28
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.
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 29
=== 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
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 30
treat Docs-as-Code IV: automate
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 31
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
.docx bzw. MS Word
...bzw. pdf
Zusammenarbeit
Aber alle anderen Dokumente sind in Confluence…
Confluence speichert die Seiten intern als xhtml
…und hat eine REST-API
et voilá…
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 36
Zusammenarbeit
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 37
Zusammenarbeit
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 38
Zusammenarbeit
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 39
Zusammenarbeit
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 40
Zusammenarbeit
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 41
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 Tests!
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 42
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
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 43
Automatisiertes Testing der Doku
https://github.com/aim42/htmlSanityCheck
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 44
… demnächst: Linting
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 45
http://www.hemingwayapp.com/
https://github.com/btford/write-good
Bonus: Export PPT
▪Sprechernotizen enthalten asciidoc
▪Slides und asciidoc werden automatisch exportiert
Bonus: Export PPT
docToolchain
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 48
Fragen? Antworten!
20.02.2018 @RalfDMueller @arc42Tipps @docToolchain 49
https://doctoolchain.github.io
https://doctoolchain.github.io/docToolchain
https://jaxenter.de/tag/hhgdc
https://docs-as-co.de
https://arc42.org
Clipart: presentermedia.com, licenced to [email protected]
@docToolchain
@RalfDMüller
https://rdmueller.github.io
@docToolchain