Docs-as-Code: Anatomie einer realen Systemdokumentation

W-Jax, 6.11.2018, München
https://jax.de/software-architecture/docs-as-code-anatomie-einer-realen-systemdokumentation/

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

In diesem Vortrag zeigen Ralf und Gernot anhand eines (kleinen aber) realen Projekts, wie Sie Schritt für Schritt den Docs-as-Code-Ansatz verwirklichen können. Von Anforderungs- und Architekturdokumentation bis hin zu Developer-Guidelines ist alles einfach, pragmatisch und zum direkten Konsum („wiederverwenden“) geeignet. Sie erleben (live), wie Sie mehrere Dokumentationsartefakte kombinieren können, für verschiedene, zielgruppenunterschiedliche Ausgaben generieren und plattformübergreifend nebenbei noch eine Website für Ihre Doku zaubern können. Neben diversen Good Practices zeigen Ralf und Gernot auch die Probleme und Grenzen einiger Ansätze auf. Format: Viel Demo, wenige Slides, Github-Repository zum selbst ausprobieren.

Transcript

1. Docs-as-Code: Anatomie einer realen Systemdokumentation Dr. Gernot Starke & Ralf D. Müller W-JAX 2018
2. 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
3. ... aus der Realität einer Open-Source Initiative... • Umfangreiches „Reference Manual“ (> 100 Abschnitte) mit Querverweisen, Diagrammen, Literaturverweisen usw. • Bestehende Link-Checker ungeeignet • => besser machen!!
4. ... Nebenziel • Praxisbeispiel für arc42-Einsatz mit Docs-As-Code, asciiDoc & Co.
5. HTML Sanity Checker Pragmatic HTML Checking and arc42 Case Study https://github.com/aim42/htmlSanityCheck
6. (Business) Goal shall support authors creating digital formats by checking hyperlinks, images and and similar resources.
7. Overview
8. Goal (Output) • HTML Report • Summary for humans • Results by page • Minimally styled • Console Report • JUnit XML Report
9. 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)
10. Intro: Why can it go wrong? • Markup languages simplify links and references, but: • generated links sensitive to spelling, typos, renames, deletes
11. 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:
12. Treat Docs-as-Code
14. Demo-Time! Asciidoc
15. arc42
17. Demo-Time! Modules
19. Source-Code:
22. Danke für Ihre Aufmerksamkeit! https://docs-as-co.de