Tech-Talk: Repository-übergreifende Dokumentation mit Antora

«Everything as Code» – unter diesem Motto präsentierte Sebastian Graf in seinem Tech Talk einen eleganten Ansatz: Lern- und Unterrichtsinhalte konsequent versioniert, automatisiert und zentral publiziert – mit Tools, wie sie aus der Softwaredokumentation bekannt sind.

Der Wildwuchs an Plattformen – von Moodle über Teams bis hin zum Active Directory – erschwert es, strukturierte und aktuelle Lehrinhalte den Studierenden zugänglich zu machen. Die Idee: Dokumentation wird nicht mehr als Word-Datei oder OneNote geführt, sondern «as Code», etwa in Markdown oder AsciiDoc – versioniert im Git-Repository.

Mit Tools wie mkdocs oder Jekyll lassen sich aus diesen textbasierten Formaten statische Webseiten generieren – optisch ansprechend, leichtgewichtig und ideal für die Veröffentlichung einzelner Module oder Projekte. In Kombination mit CI/CD-Pipelines können diese Seiten automatisch gebaut und über GitLab Pages bereitgestellt werden – ganz ohne eigenen Webserver.

Doch wie lassen sich viele solcher Dokumentationen zu einer übergeordneten, zentralen Website zusammenführen? Hier kommt Antora zum Einsatz: Ein Framework, das Inhalte aus mehreren Repositories aggregiert. Über eine zentrale Konfigurationsdatei in einem «Haupt-Repo» werden Struktur, Navigation und einzubindende Quellen (Repos) definiert. So bleibt die dezentrale Pflege einzelner Module möglich – bei gleichzeitiger zentraler Veröffentlichung.

Eine konsequente Fortführung dieser Vision «Everything as Code» zeigt Sebastian Graf mit «Feedback as Code»: Ein praktisches Beispiel aus dem FHNW Cloud-Modul demonstriert, wie das aussehen kann: Mittels Ansible-Skripten wird dort automatisiert überprüft, ob Studierende ihre Server korrekt aufgesetzt haben. Die Testergebnisse werden als strukturierte Reports im Git-Repository abgelegt – versioniert, nachvollziehbar und automatisiert generiert. Diese Feedback-Daten werden anschliessend über Antora in die zentrale Dokumentation integriert – und somit Teil eines ganzheitlichen, dokumentierten Lernprozesses.

Mit Antora und dem «Everything as Code»-Ansatz entstehen neue Möglichkeiten, Lehrinhalte strukturiert, aktuell, effizient und konsistent zugänglich zu machen.

Blog Beitrag: Simon Freiermuth (simon.freiermuth@fhnw.ch), MSE Student und Assistent am IMVS