BillionPhotos.com - stock.adobe.
Automatisierte Dokumentation – zu gut, um wahr zu sein?
Die meisten Programmierer beschäftigen sich nur ungern mit der Dokumentation. Automatisierte Tools können ihnen einiges an – wenn auch nicht die ganze – Arbeit abnehmen.
Die meisten Programmierer vermeiden Dokumentationsaufgaben, soweit sie können. Schnell hat man sich selbst eingeredet, dass der Code selbsterklärend ist, oder dass man die Dokumentation am besten erst ganz am Schluss erledigt.
Auf Codeebene fängt das Thema Dokumentation bereits damit an, aussagekräftige Namen wie Kunde_Name, Kunde_Code oder Kunde_Straße_Adresse zu verwenden. Das ist eine vergleichsweise einfache Maßnahme, die es trotzdem noch lange nicht in allen Unternehmen gibt. Wenn Änderungen erforderlich sind, müssen die neuen Programmierer aufwändig den Inhalt der Dateien durchsuchen, bis sie die notwendigen Informationen gefunden haben.
Mittlerweile gibt es jedoch glücklicherweise eine Vielzahl ausgereifter Dokumentationssysteme. Neuere Ansätze sehen vor, dass eine manuelle Dokumentation – besonders erzwungene manuelle Dokumentation – nicht immer erforderlich ist.
Das richtige Werkzeug wählen
CASE-Tools (Computer Aided Software Engineering) verfügen häufig über Funktionen für die automatische Dokumentation. Diese generieren folgende Dokumente:
- Datenfluss- und Entitätsmodelle;
- ein übergeordnetes Designdokument;
- ein Anforderungs-/Modellbeziehungsdokument;
- eine Funktions- und Prozessbeschreibung;
- eine Reihe von Testfällen; und
- Systemadministratordokumentation.
Betrachten Sie die Dokumentation nicht als etwas, das Sie schreiben und vergessen können, sondern als lebendiges, sich ständig im Fluss befindliches Informationsdepot.
Außerdem sollte sie neben den technischen Eckdaten noch weitere Aspekte abbilden:
- Kosten
- Timelines
- Berichte und Metriken
- Helpdesk-Dokumentation
- Endbenutzerdokumentation
CASE-Tools müssen dazu passen, wie Ihr Unternehmen seine Werkzeuge entwickelt. Die Tage monolithischer Anwendungen, die auf eigener Hardware laufen sind gezählt. Sie weichen zunehmend virtualisierten, Cloud-basierten Plattformen, die mit virtuellen Maschinen (VMs) und Microservices arbeiten.
Kaskaden- oder Wasserfallansätze für das Projektmanagement haben sich durch agile Methoden in der DevOps-Welt der kontinuierlichen Entwicklung und Bereitstellung sowie der kontinuierlichen Verbesserung überlebt. Dies macht die fortlaufende Aktualisierung der Dokumentation zeitgleich schwieriger und zwingender notwendig. Organisationen sollten sicherstellen, dass alle in Betracht gezogenen Tools zu ihren eigenen Ansätzen für den Lebenszyklus der Softwareentwicklung passen. Administratoren müssen verstehen, welche Teile des Dokumentationsprozesses automatisiert werden können und welche manuelle Eingriffe erfordern.
Automatisierung der DevOps-Dokumentation
Moderne DevOps-Systeme erstellen Dokumente, welche die Punkte aus dem ersten Aufzählungsblock in diesem Artikel abdecken – abgesehen von den Testfällen und den Systemadministratordokumenten. Nur wenige können jedoch auch den zweiten Satz Dokumente erstellen. Sie bleiben die Aufgabe technischer Autoren – Menschen, die Code und Prozesse mit einem feinen Kamm durchgehen, um eine zweckdienliche Dokumentation zu erstellen.
Die Endbenutzerdokumentation sollte für einen Endbenutzer lesbar und verständlich sein; sie sollte keine technischen Begriffe enthalten, die Ihre Zielgruppe nicht kennt. Sie sollte außerdem nicht in Form schreibgeschützter Online-PDFs oder gar ausgedruckt vorliegen. Sie muss dort verfügbar sein, wo Anwender sie benötigen – direkt in der Anwendung, nur einen Klick entfernt und idealerweise im zugehörigen Kontext.
Die meisten DevOps-Tools mit visuellen Umgebung – wie Chef und Puppet – ermöglichen Drag-and-Drop-Ansätze zum Entwerfen eines Top-Level-Modells. Die Tools erstellen die Datenfluss- und Entitätsmodelle zusammen mit den Funktions- und Prozess-Flows. Orchestrierungs-Tools, wie die von HashiCorp, BMC und Stonebranch, bieten zusätzliche Funktionen mit tiefgreifenderen Fähigkeiten, um APIs abzubilden.
Cloud-Anbieter wie AWS und Azure verfügen in der Regel über Frontends, die dabei helfen, Grundlagen zu erstellen und zu pflegen, die zur Dokumentation einer DevOps-Umgebung erforderlich sind.
Verlassen Sie sich jedoch nicht nur auf die Tools, um eine umfangreiche Dokumentation bereitzustellen. Sie müssen alles manuell überprüfen. Eine grundlegende automatisierte Dokumentation erspart es Ihnen, dicke Wälzer selbst zu schreiben. Sie brauchen aber auch den Blick des menschlichen Lesers, um sicherzustellen, dass die Grundsteine Benutzer-, Admin- und Helpdesk-Dokumentation nicht durch ein fehlerhaftes Automatisierungsprojekt eine Flut von Tickets und Fehlern verursachen.
Erfassen und analysieren Sie die Zusammenarbeit zwischen DevOps-Teams. Achten Sie auf Systeme für die Zusammenarbeit – wie GitHub, Slack oder Chats innerhalb der zugrunde liegenden DevOps-Pakete – und Projektmanagement-Funktionen von Paketen, wie Jira von Atlassian. Diese erstellen aus einfachen visuellen Eingaben die erforderliche Dokumentation.
Die Automatisierung der DevOps-Dokumentation befindet sich noch am Anfang ihrer Reise, aber die ersten Schritte sind in Bewegung. IT-Organisationen müssen sicherstellen, dass die gewählten Tools miteinander kompatibel sind. Sonst schaffen Sie mehrere, nicht miteinander verknüpfte Dokumentationen, die schwer zu pflegen und konsistent zu halten ist. Suchen Sie nach flexiblen Tools, die eine einfache Nutzung über visuelle Frontends und kollaborative Erfassung ermöglichen, mit einer Kapazität für den dezentralen Zugriff durch Systemadministratoren und Helpdesk-Mitarbeiter.
