Docs-as-Code: Anatomie einer realen Systemdokumentation

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.

Cc5f3bf8b3cb91c985ed4fd046aa451d?s=128

Ralf D. Müller

November 06, 2018
Tweet

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

  13. None
  14. Demo-Time! Asciidoc

  15. arc42

  16. None
  17. Demo-Time! Modules

  18. None
  19. Source-Code:

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