Die Kunst der Software-Dokumentation
Welche Tools sind sinnvoll?
Autor: Peter Herklotz, Softwarearchitekt TRANSCONNECT®
“Als Softwarearchitekt kenne ich das Gefühl, wenn die Rede auf Software-Dokumentation kommt und einige behaupten, es sei nur Zeit- und Ressourcenverschwendung. Doch glauben Sie mir, eine gut durchdachte Dokumentation ist wie das kleine Büchlein für den rot blinkenden Geschirrspüler: unverzichtbar und Ihr bester Freund in Zeiten der Not.”
Peter Herklotz, Softwarearchitekt TRANSCONNECT®
Warum Dokumentation?
Ich verstehe, dass die eigentliche Programmierung viel verlockender erscheint als das Schreiben von Dokumentationen. Aber unser Ziel als Entwickler:innen sollte sein, Code zu verstehen, zu warten, zu erweitern und neue Teammitglieder reibungslos einzuarbeiten. Eine klare Dokumentation ist hierbei der Schlüssel.
Code ist nie Dokumentation genug!
Ja, der Code sollte für sich selbst sprechen, aber erzählt er auch die ganze Geschichte? Hilft er die Deployment-Infrastruktur zu verstehen? Und was ist mit dem Nutzerhandbuch? Die Dokumentation ermöglicht es, den Code in einem größeren Kontext zu verstehen. Sie ist nicht nur eine Aufgabe, sondern ein Werkzeug, um Entscheidungen zu reflektieren, Anforderungen zu überprüfen und die komplexe Architektur zu verstehen.
Nennen Sie mir einfach die Tools...
Wenn Sie mir versprechen, dass Sie sich von Vorurteilen gegenüber Dokumentationsaufgaben verabschieden, kommen hier die Tools, die den Prozess schmerzfrei gestalten. Diese Tools sind nicht nur effizient, sondern auch teamübergreifend nutzbar, helfen bei der Versionierung und bieten die Möglichkeit schnell Unterschiede in der Dokumentation zu erfassen. Mit ausdrucksstarker Markup-Sprache und Multi-Repo Docs wird die Dokumentation zum Kinderspiel. Es ist wirklich kein Hexenwerk!
AsciiDoc ist eine umfassende und trotzdem schnell zu erlernende Markup Sprache. Von Textformatierung über Tabellen und Bildern bis zur automatischen Generierung von Inhaltsverzeichnissen bleibt kein Wunsch unerfüllt. Und am Ende können Sie das Ergebnis als PDF oder Webseite erzeugen lassen.
Mit Antora können Sie die Dokumentation mehrerer Teilkomponenten aus verschiedenen Git-Repositories zu einer Webseite zusammenführen. Dabei ist auch eine Versionierung möglich und das Generieren von Dokumentation für mehrere parallele Versionen.
Für eine Dokumentation, die sich an Nutzende richtet, ist ein einheitliches Sprachbild sinnvoll. Große Firmen wie Microsoft oder Google haben dafür einen Editorial Styleguide aufgestellt. Dieser regelt Fragen der Groß- und Kleinschreibung sowie Punktation in Überschriften oder auch die maximale Satzlänge. So bleibt die Dokumentation sprachlich konsistent, auch wenn mehrere Menschen daran arbeiten.
Mit Vale (vale.sh) kann man diese Regeln aufstellen und automatisiert prüfen. Und es gibt auch fertige Regelpakete, welche direkt genutzt werden können.
KI in der Dokumentation?
Sie fragen sich vielleicht, ob KI auch bei der Dokumentation helfen kann. Meine Antwort lautet: Ja. Aber nicht als Ersatz, sondern als Ergänzung. KI-Programme schneiden bei Standardaufgaben zwar nicht schlecht ab, aber die menschliche Intuition ist unschlagbar. Die technische Dokumentation bietet die Möglichkeit, Entscheidungen zu reflektieren, Anforderungen zu überdenken und die Logik zu durchdenken. Hier liegt der menschliche Vorteil gegenüber KI. Nutzen Sie daher die Chance zum Review!
Unser Weg
In unserem TRANSCONNECT® Team sind wir gerade dabei, einen Doku-Stack aufzubauen, der für uns am besten funktioniert. Wir verbinden Mensch und KI, um schnell die besten Ergebnisse zu erzielen. Mit Tools wie AsciiDoc, Antora und Vale gestalten wir die Dokumentation effizient und sprechen sowohl die Sprache der Entwickler:innen als auch die der Linguisten.
Wie integrieren Sie Ihre KI-Werkzeuge?
Nachdem wir festgestellt haben, dass KI eine wertvolle Ergänzung, aber kein Ersatz für die menschliche Intuition in der technischen Dokumentation ist, stellt sich die Frage, wie wir diese beiden Kräfte am besten kombinieren können.
Im Unternehmenskontext ist insbesondere die IT-Infrastruktur durch eine heterogene Systemlandschaft gekennzeichnet, was den Einsatz von KI-Werkzeugen intern erschwert, da diese Werkzeuge in der Regel auf Standardmodelle trainiert sind. Wir im TRANSCONNECT®-Team haben diese Herausforderungen (heterogene Systemlandschaft und notwendige große Mengen von Trainingsdaten) erkannt und eine nachhaltige Lösung dafür entwickelt, die bei hunderten von Kunden im Einsatz ist.
Aber was ist TRANSCONNECT®?
TRANSCONNECT® ist eine moderne Integrationsplattform, die es Unternehmen ermöglicht, verschiedene Systeme, Datenquellen und Anwendungen effizient zu verbinden. Sie nutzt fortschrittliche künstliche Intelligenz und maschinelles Lernen, um die Datenintegration und -verarbeitung zu optimieren.
Wie lösen wir die oben besprochene Herausforderung?
TRANSCONNECT® ermöglicht ein effizientes Daten-Mapping und die Transformation großer Datenmengen innerhalb des Lernprozesses eines KI-Tools, was sich sehr positiv auf die Anpassungsfähigkeit von KI-Modulen auswirken kann. Dies führt zu einer deutlichen Verbesserung und Beschleunigung der Prozessautomatisierung.
Sie interessieren sich für TRANSCONNECT®?
Jetzt einen unverbindlichen Termin vereinbaren.
Lernen Sie uns näher kennen!
Lernen Sie uns näher kennen!
Verpassen Sie keine News.
Stellen Sie Ihre Fragen.
Tauschen Sie sich mit uns aus.
Lernen Sie uns näher kennen!
Verpassen Sie keine News.
Stellen Sie Ihre Fragen.
Tauschen Sie sich mit uns aus.
