Docs-as-Code: Anatomie einer smarten Systemdokumentation

OOP, 22.01.2019, München

https://www.oop-konferenz.de/oop2019/programm/konferenzprogramm/sessiondetails/action/detail/session/di-61-4/title/docs-as-code-anatomie-einer-smarten-systemdokumentation.html

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

Transcript

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