Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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.

Ralf D. Müller

January 22, 2019
Tweet

More Decks by Ralf D. Müller

Other Decks in Programming

Transcript

  1. 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
  2. ... aus der Realität einer Open-Source Initiative... • Umfangreiches „Reference

    Manual“ (> 100 Abschnitte) mit Querverweisen, Diagrammen, Literaturverweisen usw. • Bestehende Link-Checker ungeeignet • => besser machen!!
  3. HTML Sanity Checker Pragmatic HTML Checking and arc42 Case Study

    https://github.com/aim42/htmlSanityCheck
  4. Goal (Output) • HTML Report • Summary for humans •

    Results by page • Minimally styled • Console Report • JUnit XML Report
  5. 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)
  6. Intro: Why can it go wrong? • Markup languages simplify

    links and references, but: • generated links sensitive to spelling, typos, renames, deletes
  7. 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: