Docs-as-Code: Anatomie einer smarten Systemdokumentation

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.

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

January 22, 2019
Tweet

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
  3. None
  4. None
  5. None
  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

  16. None
  17. Asciidoc Demo-Time!

  18. None
  19. arc42

  20. None
  21. None
  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

  26. None
  27. Source-Code:

  28. None
  29. None
  30. Open Source, Work-in-Progress...

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