© StockVector/Shutterstock.com
Generierung der Dokumentation einer Microservices-Landschaft

Dynamische Doku


Eine gute Dokumentation gilt als Aushängeschild eines Systems. Doch meist wird sie als notwendiges Übel betrachtet und daher viel zu oft vernachlässigt. Dabei ist eine lückenhafte und veraltete Dokumentation ein risikobehafteter Bereich mit viel Konflikt- und Fehlerpotenzial. Um die Risiken zu vermeiden, haben wir uns auf die Suche nach einer dynamischen und flexiblen Lösung gemacht. Die Ergebnisse stellen wir euch hier vor.

Dokumentationen sind wartungsintensiv und stimmen oft nicht mit der Realität – also dem Code – überein. Der aktuelle Trend, im Enterprise-Umfeld auf Microservices zu bauen, vereinfacht das Problem nicht: Der Endanwender will und soll nicht wissen, dass das System in verschiedene Teilsysteme aufgeteilt ist. Das Handbuch jedoch hat deshalb an dieser Stelle weiterhin monolithischen Charakter. Eine einheitliche, zentrale Dokumentation über verschiedene Systeme, Programmiersprachen und Quellen hinweg stellt eine Herausforderung dar.

In unserem Unternehmen sind wir auf genau dieses Problem gestoßen. Eine Softwaresuite, bestehend aus mehreren Subsystemen – teilweise modular und kundenspezifisch erweiterbar –, bedarf eines nach außen einheitlichen Handbuchs. Da direkt miteinander konkurrierende Firmen diese Software verwenden, darf unter keinen Umständen versehentlich die Dokumentation von Kunde A zu Kunde B gelangen. Dennoch soll die Doku stets vollständig und aktuell sein. Und natürlich sollte sie keinen Aufwand generieren.

Einheitliche Sprache

Eine Dokumentation entspringt aus unterschiedlichsten Quellsystemen. Diese sind in unterschiedlichen Sprachen geschrieben und liefern Informationen in diversen Strukturen. Um ein zentrales Dokument zu erhalten, müssen wir zunächst eine einheitliche Sprache für die Dokumentation wählen.

Entwickler lieben Markdown (jedenfalls die meisten). Spätestens seit GitHub jedes Repository mit einer readme.md ansprechend formatiert anzeigt, sollte die Auszeichnungssprache zum Standardrepertoire eines jeden Entwicklers gehören. Mit dem Open-Source-Programm Pandoc [1] lässt sich Markdown komfortabel in verschiedene Formate wie HTML oder PDF, aber auch in EPUP, DOCX oder in einen modernen Reveal.js-Foliensatz konvertieren.

Wir konzentrieren uns im Folgenden auf die Erstellung eines PDFs, da dieses Format häufig für die Dokumentation einer Enterprise-Software verwendet wird. Wird eine Markdown-Datei mit Pandoc in PDF konvertiert, wird als Zwischenformat LaTeX verwendet. Darum verwundert es nicht, dass alle relevanten Features, die man im Rahmen einer guten Dokumentation benötigt, von Pandoc implizit erfüllt werden.

  • Überschriften unterschiedlicher Größe

  • Textformatierungen fett, kursiv, unterstrichen

  • Hyperlinks mit Titel

  • Listen

  • Referenzen/Verlinkungen innerhalb des Texts

  • Fußnoten

  • Tabellen und Tabellenstyles

  • Bilder mit Bildunterschriften

  • Code sowohl inline als auch im Block

  • Verweise auf Literatur, auch mit unterschiedlichen CSL-Formaten

  • mathematische Formeln, sowohl inline als auch im Block

  • Literatur-, Abbildungs-, Inhaltsverzeichnisse

  • Verweise auf Literatur samt Verzeichnis

  • Styling mit eigenen Templates

Ein Beispiel-Markdown, in dem die meisten der aufgezählten Features enthalten sind, findet sich in Listing 1. Um es in ein PDF-Dokument umzuwandeln, muss Pandoc nicht unbedingt nativ installiert werden, es gibt zahlreiche Docker Images, die dieses Programm samt LaTeX mitbringen. Der Kommandozeilenaufruf in List­ing 2 verwendet das offizielle Image pandoc/latex in der Version 2.6. Die referenzierte Markdown-Datei input.md muss hierzu im aktuellen Verzeichnis liegen. Das Output-Format der Datei result.pdf wird implizit über die Dateiendung bestimmt. Das vollständige Codebeispiel findet man als Gist bei GitHub unter [2]. Dort ist auch der entsprechende Aufruf für die Windows-Kommandozeile zu finden.

Listing 1

--- title: Dynamische Dokumentation author: Simone Görner und Richard Vogel lang: de lof: yes --- # Pandoc ![Pandoc Logo](logo.png){width=15%} ## Kurzvorstellung [Pandoc](https://pandoc.org) bietet **dicke** und *schräge* Features wie Fußnoten[^note], `inline`-Code sowie [^note]: mehr siehe @book1. ```java // Codeblöcke System.out.println("Mit Highlighting") ``` Da Markdown über $LaTeX$ zu PDF transformiert wird, bekommt man Features wie mathematische Formeln $$ e^i\pi=-1 $$ geschenkt. Hierzu gehören auch Tabellen und Abbildungen sowie - Inhaltsverzeichnis - Abbildungsverzeichnis. ## Literaturverzeichnis

Listing 2

# Erstellung eines PDFs aus einer Markdown-Datei samt Referenzen im Bibtex-Format docker run -v `pwd`:/data \ pandoc/latex:2.6 \ input.md \ -F pandoc-citeproc \ --bibliography references.bib \ --toc \ -o result.pdf

Pandoc ist erweiterbar. So gibt es bereits einige Filter, die z. B. chemische Formeln formatieren oder UML-Diagramme aus Code-Snippets erzeugen. Für eigene kleine Anforderungen lässt sich mit der Skriptsprache Lua schnell und einfach ein eigener Pandoc-Filter schreiben.

Markdown dynamisieren?

Fast jeder Entwickler kennt das Problem, dass Dokumentationen doppelt gepflegt werden müssen. Einmal direkt im Code, damit auch weitere Entwickler die Aufgabe der Klasse oder Methode kennen, und zusätzlich noch in einem separaten Dokument, das dem Kunden als fachliche Dokumentation zur Verfügung gestellt wird. Hier ist die Gefahr groß, dass bei einer Änderung nur eine der beiden Stellen angepasst wird und es dadurch zu auseinanderlaufenden Dokumentationen kommt. Dieses Problem lässt sich durch einen dynamischen Ansatz lösen. Prinzipiell steigt bei Entwicklern die Motivation, sich der Dokumentation zu widmen, wenn sie direkt am Code erfolgt, da das auch für die eigene Übersicht hilfreich ist.

Als weitere positive Argumente sind die Versionier- und Wartbarkeit von Markdown-Dateien zu nennen. Da in Softwareprojekten immer (!) eine Versionsverwaltung verwendet werden sollte, können User Änderungen an der Dokumentation direkt nachvollziehen, wodurch sie sich zudem sehr wartungsfreundlich gestaltet.

Der dynamische Ansatz schafft generell eine Möglichkeit zur kontinuierlichen Dokumentation. Automatisierbarkeit spielt eine immer zentralere Rolle, sie ist auch bei der Dokumentation wünschenswert. Für Entwickler fühlt es sich ohnehin angenehmer an, Dokumentationen zu „programmieren“, anstatt sie nur zu schreiben.

Ein weiterer Vorteil ist, da...

Neugierig geworden? Wir haben diese Angebote für dich:

Angebote für Gewinner-Teams

Wir bieten Lizenz-Lösungen für Teams jeder Größe: Finden Sie heraus, welche Lösung am besten zu Ihnen passt.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang