Docs-as-Code: Anatomie einer smarten Systemdokumentation

Slide 1

Slide 1 text

Docs-as-Code: Anatomie einer realen Systemdokumentation Dr. Gernot Starke & Ralf D. Müller OOP 2019

Slide 2

Slide 2 text

Diese Session haben wir als Live-Coding Session durchgeführt, deshalb machen die Slides nur einen unvollständigen Eindruck. Alle Infos gibt es jedoch auf https://docs-as-co.de Das Repository unseres Beispiel ist auf https://github.com/aim42/htmlSanityCheck zu finden

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

... aus der Realität einer Open-Source Initiative... • Umfangreiches „Reference Manual“ (> 100 Abschnitte) mit Querverweisen, Diagrammen, Literaturverweisen usw. • Bestehende Link-Checker ungeeignet • => besser machen!!

Slide 7

Slide 7 text

... Nebenziel • Praxisbeispiel für arc42-Einsatz mit Docs-As-Code, asciiDoc & Co.

Slide 8

Slide 8 text

HTML Sanity Checker Pragmatic HTML Checking and arc42 Case Study https://github.com/aim42/htmlSanityCheck

Slide 9

Slide 9 text

(Business) Goal shall support authors creating digital formats by checking hyperlinks, images and and similar resources.

Slide 10

Slide 10 text

Overview

Slide 11

Slide 11 text

Goal (Output) • HTML Report • Summary for humans • Results by page • Minimally styled • Console Report • JUnit XML Report

Slide 12

Slide 12 text

Intro: What can go wrong... • Common HTML generators* guarantee syntactic correctness *: Especially Markdown, AsciiDoc, AsciiDoctor • Potential semantic errors: • Broken links, i.e. • Broken cross references • Broken imageMaps • Missing images • Ambiguous definitions • Unused resources (i.e. image files)

Slide 13

Slide 13 text

Intro: Why can it go wrong? • Markup languages simplify links and references, but: • generated links sensitive to spelling, typos, renames, deletes

Slide 14

Slide 14 text

Current Status Used in practice: • http://www.vogella.com/ • https://aim42.org • https://github.com/zaproxy • <...> Many open issues: • Mostly enhancements • Port to maven • (Graphical) UI • Documentation issues Light activity in repository:

Slide 15

Slide 15 text

Treat Docs-as-Code

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

Asciidoc Demo-Time!

Slide 18

Slide 18 text

No content

Slide 19

Slide 19 text

arc42

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

https://leanpub.com/arc42-primer https://leanpub.com/arc42byexample

Slide 23

Slide 23 text

Demo-Time! Modulare Doku…

Slide 24

Slide 24 text

Einschub: Drama!

Slide 25

Slide 25 text

Lösung in AsciiDoc: Level-Offset

Slide 26

Slide 26 text

No content

Slide 27

Slide 27 text

Source-Code:

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

No content

Slide 30

Slide 30 text

Open Source, Work-in-Progress...

Slide 31

Slide 31 text

Danke für Ihre Aufmerksamkeit! https://docs-as-co.de