Docs-as-Code: Anatomie einer realen Systemdokumentation

Slide 1

Slide 1 text

Docs-as-Code: Anatomie einer realen Systemdokumentation Dr. Gernot Starke & Ralf D. Müller W-JAX 2018

Slide 2

Slide 2 text

Diese Session wurde als Live-Coding durchgeführt, deshalb (fast) keine Slides. 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

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

Slide 4 text

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

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

Overview

Slide 8

Slide 8 text

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

Slide 9

Slide 9 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 10

Slide 10 text

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

Slide 11

Slide 11 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 12

Slide 12 text

Treat Docs-as-Code

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

Demo-Time! Asciidoc

Slide 15

Slide 15 text

arc42

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

Demo-Time! Modules

Slide 18

Slide 18 text

No content

Slide 19

Slide 19 text

Source-Code:

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

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