Schulung | Ausgezeichnete Softwaredokumentation

Motivation

Der grossen Bedeutung von Softwaredokumentation lässt sich heute mit zeitgemässeren Umgebungen als Word oder Confluence begegnen.

Mit einer vereinfachten Auszeichnungssprache – hier AsciiDoc – lassen sich die Dokumente nämlich in jedem beliebigen Texteditor erstellen und bearbeiten. Dabei bleiben alle Inhalte und Konfigurationen einfach lesbar und editierbar, und das ganz ohne eigenwillige WYSIWYG-Programme oder Wiki-Plattformen.

Softwareentwickler schätzen die Nähe zwischen Programmcode und Dokumentation sowie die Möglichkeit, die Rohdokumente direkt unter Versionsverwaltung zu stellen. Leser aller Zielgruppen schätzen das professionelle, einheitliche und gepflegte Erscheinungsbild einer so generierten Dokumentationsstruktur.

Ausgezeichnete Softwaredokumentation gelingt durch einen ganzheitlichen Ansatz aus a) vereinfachter Auszeichnungssprache, b) Dokumentationsgenerator und c) einfach umsetzbaren organisatorischen Massnahmen – also genau das, was Sie in diesem Workshop lernen werden.

Programm

Der Schwerpunkt liegt im Kennenlernen und Üben von AsciiDoc als vereinfachte Auszeichnungssprache sowie Antora als perfekt dazu passenden Dokumentationsgenerator. Sie erleben, wie ausgewählte Diagrammtypen aus textuellen Beschreibungen erzeugt werden können und das Erscheinungsbild gesamter Dokumentationsstrukturen zentral angepasst werden kann. Begleitet wird all das von lehrreichen Erläuterungen zum organisatorischen Wer, Wie und Was der Softwaredokumentation.

  • Tag 1 | AsciiDoc
    • Bedeutung und Arten von Softwaredokumentation
    • Docs as Code als nachhaltige Alternative zu Word und Confluence
    • AsciiDoc als vereinfachte Auszeichnungssprache
      • Textstrukturierung und -formatierung
      • Klassische und spezielle Dokumentationsbausteine
      • Einbinden von Code-Snippets und anderen Dokumenten
    • Diagrams as Code als textuelle Alternative zum «Kästchenschieben»
    • Ausblick auf Dokumentationsvorlagen und automatische Verifizierung von Architekturvorgaben mittels ausführbarer Dokumentation
  • Tag 2 | Antora
    • Einführung in Antoras Grundkonzepte
      • Site
      • Component
      • Module
      • Version
      • Playbook
    • Strukturierung einer Dokumentation in Module und Komponenten
    • Zentrale Anpassung des Look & Feels und der Navigation
    • Zusammenspiel mit Versionsverwaltungssystemen
    • Kurzer Einblick in die Hauptalternative reStructuredText / Sphinx (hauptsächlich für Python-Projekte)

Kursziele

Dieser zweitägige Workshop wird bzgl. Softwaredokumentation mit Sicherheit viel zur Klarheit beitragen, neue Ideen liefern und bisher unbekannte Türen öffnen. Sie erfahren, wieso bisherige Versuche, die eigene Softwarearchitektur zu dokumentieren, im besten Fall nur kurzfristig funktionierten. Anhand vieler eigenhändiger praktischer Beispiele können Sie sich einen Überblick über die eindrücklichen Möglichkeiten verschaffen, die sich mit einem Docs-as-Code- und Diagrams-as-Code-Ansatz ergeben.

Zielgruppen

  • Alle im Softwarebereich tätigen Personen (Entwickler, Architekten, Projekt- und Produktmanager, Abteilungs- und Teamleiter, Entscheider etc.)

Referent

Christian Heitzmann ist Java-, Python- und Spring-zertifizierter Softwareentwickler mit einem CAS in Machine Learning und Inhaber der SimplexaCode AG in Luzern. Er entwickelt seit über 20 Jahren Software und gibt seit über 12 Jahren Unterricht und Kurse im Bereich der Java- und Python-Programmierung, Mathematik und Algorithmik. Als Technical Writer dokumentiert er Softwarearchitekturen für Unternehmen und schreibt regelmässig Artikel für IT-Fachzeitschriften.

Ausgezeichnete Softwaredokumentation 1 Ausgezeichnete Softwaredokumentation 2

Kurzlink auf diese Seite: link.simplexacode.ch/nj382024.03