© StockVector/Shutterstock.com
Java Magazin
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.

Simone Görner, Richard Vogel


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 mathem...

Java Magazin
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.

Simone Görner, Richard Vogel


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 mathem...

Neugierig geworden?


    
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang