platzhalter für titelbild hier können sie bilder aus der ... 2019 (19.03...ralf d. müller...

arc42, AsciiDoc, Gradle & Co. Im Einsatz

DB Systel GmbH | Ralf D. Müller | JavaLand | Brühl | 19.03.2019

Platzhalter für Titelbild – Hier können Sie Bilder aus der Mediathek einfügen!Placeholder for title picture – You can insert here pictures from the Mediathek!

Docs-as-Code

DB Systel GmbH | Ralf D. Müller | 19.03.20192

Incomplete or confusing documentation#1 Problem with Open Source

Ralf D. Müller

Software Architect @ DB Systel mit Schwerpunkt

Web-Technologien

Qualität (Security, Testautomation)

Produktivität (Gradle, Groovy, Grails)

Prozessoptimierung

In der Freizeit Geek, arc42 Contributor &Maintainer von docToolchain

Dr. Gernot Starke – innoQ Fellow

Softwarearchitektur

Entwurf

Evolution + Modernisierung

Dokumentation

Reviews

+49 177 7282570gernot.starke@innoq.com

Was machen wir die nächsten 40 Minuten?

Mischung aus Tipps zu arc42 und docs-as-codeBest Practice zum Umgang zur Pflege einer

ArchitekturdokumentationExperimentelle Features :-)Vorschläge aus Erfahrung, keine Silver Bullet

Was ist Docs-as-Code?

DB Systel GmbH | Ralf D. Müller |19. März 20198

,--._______,-.

,',' , . ,_`-.

/ / ,' , _` ``. | ) `-..

(,';'""`/ '"`-._ ` \/ ______ \\

: ,o.-`- ,o. )\` -' `---.))

: , d8b ^-. '| `. ` `.

|/ __:_ `. | , ` ` \

| ( ,-.`-. ;' ; ` : ;

| | , `. / ; : \

;-'`:::._,`.__),' : ;

/ , `- `-- ; |

/ \ ` , |

( ` : : ,\ |

\ `. : : : ,' \ :

\ `|-- ` \ ,' ,-' :-.-';

: |`--.______; | : :

: / | | | \

| ; ; ; / ;

_/--' | -hrr- :`-- / \_:_:_|

,',',' | |___ \

`^._,--' / , , .)

`-._,-'

------------------------------------------------

This ASCII pic can be found at

https://asciiart.website/index.php?art=animals/dogs

VEry NOrMal System

Gewachsene Dokumentation

Unterschiedliche Stakholder

Aufgrund verschiedener Änderungen stets im Wandel

Hoher Pflegeaufwand

Das VENOM Projekt

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

Heutiger Fokus: Architektur Docs-as-Code

Wie schreibe ich eine System-Dokumentation?

Dr. Peter Hruschkahttp://www.peterhruschka.eu/

Dr. Gernot Starkehttp://gernotstarke.de/

http://arc42.org/

DAS Template für die Dokumentation eines Software Systems.

arc42 …

… ist das Standard-Template im deutschsprachigen Raum

… ist verfügbar in Deutsch, Englisch und Spanisch und Russisch

… ist verfügbar in > 9 Formaten (.adoc, .docx, .rst, .md, .tex …)

… gibt der Dokumentation eine einheitliche Struktur

… ist verfügbar mit und ohne Hilfestellung

… hilft die richtigen Aspekte richtig zu dokumentieren

arc42 – ein Kleiderschrank für Dokumentation

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

Format der Dokumentation

MS Word ist der etablierte Standard

Arc42 existiert in vielen Formaten:

Docx latex htmlAsciidoc textile confluencemarkdown

Geoff wählt AsciiDoc aufgrund vieler Vorteile AsciiDoc

arc42 als AsciiDoc Template

== 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.

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)

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“

Treat Docs-as-Code

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

demo.adoc build.gradle console output

plugins { id "org.asciidoctor.convert" version "1.5.3" }

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>

build.gradle demo.adoc console output

http://asciidoctor.org/docs/render-documents/

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

.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

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

treat Docs-as-Code I: Version Control

.adoc.adoc.adoc .html

treat Docs-as-Code II: Git-Flow

treat Docs-as-Code III: Build-Server

Build-Server

On Change

Publish

The End?

Danke für Ihre Aufmerksamkeit!

Fragen?

Diagramme

http://plantuml.com/

http://asciidoctor.org/docs/asciidoctor-diagram/

Komplexe Diagramme als einfachen Text verwalten

PlantUML

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

Diagramme: PlantUML

draw.io

PNG-Diagramm

<xml>…

</xml>Meta-Daten

draw.io

Diagramme: Nicht malen, modellieren!

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.

{adoc:stakeholder}| Operations| Betreiber und Administratoren von VENOM| Flexibilität hinsichtlich Betriebsumgebung, Betriebssystem. Möglichst wenig Aufwand bei technischer Administration und Inbetriebnahmen. Technisches Monitoring.

=== Stakeholder

==== Users and Groups of Users

[[figure-users]]image::ea/1.5_Stakeholder.png[title="Users and Groups of Users"]

include::../../ea/stakeholder.ad[]

treat Docs-as-Code: automate!

Don‘t know how to draw your component diagrams?

=> take a look at the C4-Model by Simon Brown

https://c4model.com/

Context, Containers, Components, Classes

Diagramme

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

http://pandoc.org

.docx bzw. MS Word

...bzw. pdf

Modulare Dokumentation

arc42-master.adoc

kapitel1.adoc

kapitel2.adocpublic class HelloWorld {

public static void main (String[] args) {

// Ausgabe Hello World!

System.out.println("Hello World!");

include

kapitel8.adoc

kapitel8.1.adoc

include

business-master.adoc

security-master.adoc

Seitenumbrüche

… machen bei single-page HTML keinen Sinn

… sind aber klasse für PDF und .docx!

Apropos single-page HTML…

:data-uri:

Zusammenarbeit

Aber alle anderen Dokumente sind in Confluence…

Confluence speichert die Seiten intern als xhtml

…und hat eine REST-API

et voilá…

Zusammenarbeit: Confluence

Zusammenarbeit

Besser: statische Seiten

Besser: statische Seiten -

Zusammenarbeit - Tabellen

Tabellen in AsciiDoc

[options="header",cols="7,23,17,33,11,11"]

| Name

| Rolle

| Email

| Telefon

| Hubert Kleinschmidt

| Product Owner

| h.kleinschmidt@example.com

| 555 102

| 40388

| Erika Mustermann

| Scrum Master

| e.mustermann@example.com

| 555 103

| 41222

mit MS Excel!

Managing Tables in AsciiDoc

Export PPT

Sprechernotizen enthalten asciidoc

Slides und asciidoc werden automatischexportiert

Export PPT

Testing

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!

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

Automatisiertes Testing der Doku

https://github.com/aim42/htmlSanityCheck

… demnächst: Linting

http://www.hemingwayapp.com/

https://github.com/btford/write-good

docToolchain

Vielen Dank für Ihre Aufmerksamkeit!

https://docs-as-co.de

@docToolchain

Image-Credits: Title - Photo by Susan Yin on Unsplash Clipart: presentermedia.com, licenced to ralf.d.mueller@gmail.com

www.dbsystel.de

platzhalter für titelbild hier können sie bilder aus der ... 2019 (19.03...ralf d. müller...

Documents

introduction to testautomation presented by quontrasolutions

· der basiel systel leicht entha grill, der basie systel...

systel ip - aeq

profi-tipps profi platzhalter zitalesendel ilitas cus

platzhalter für titelbild hier können sie bilder aus der...

2016 elite systel business equipment dealers

db systel gmbh

gamme diffusion d’eau chaude - systel...

catalogue des formation systel · 2019. 10. 16. ·...

telefon(english) systel i3eng

cross mobile testautomation mit xamarin & specflow

w15 - kinsbruner - agileconnection · w15! testautomation$...

rec systel 2012 competency based recommendation

nuevos equipos y aplicaciones del sistema …...nuevos...

carpeta tecnica balanza systel 2001

ui testautomation in der praxis ... von lokalisierung bis...

db systel. digital bewegen. gemeinsam. - agile world ·...

finance & testing 2009 highspeed testautomation

effizienz im testen von sap anwendungen durch...

platzhalter für bild, bild auf titelfolie hinter das logo...