Bei der Umstellung von DevOps vernachlässigen Unternehmen oft die Qualität der Dokumentation. Für die Anwender ist sie jedoch ein wichtiger Faktor für die Wertigkeit des Produkts.
Ohne Dokumente wie Benutzerhandbücher, Beispiele, Referenzen und Änderungslisten ist kein Softwareprojekt vollständig. Sie helfen Benutzern dabei, ihre zukünftige Software zu übernehmen, bereitzustellen und zu verwenden. Ohne eine ordnungsgemäße Dokumentation kann eine noch so funktionale und leistungsstarke Software am Ende aufgrund mangelnder Akzeptanz scheitern.
In den letzten Jahren bemühten sich viele Sotwareentwickler um eine möglichst schnelle Auslieferung. Jede neue Iteration enthält Änderungen, Korrekturen und neue Funktionen. Entwickler, Admins und Nutzer können dabei leicht den Überblick verlieren. Das macht eine genaue und vollständige Dokumentation während des gesamten DevOps-Lebenszyklus wichtiger denn je.
Die traditionellen Long-Tail-Ansätze der technischen Dokumentation können jedoch nicht mit zeitgemäßen Prozessen Schritt halten. Da immer mehr Unternehmen auf DevOps und andere agile Entwicklungsparadigmen setzen, sollten sie die Art und Weise, wie IT-Abteilungen Dokumentation vorbereiten und pflegen, überdenken und aktualisieren.
Traditionelle Softwaredokumentation
Eine nützliche und effektive Dokumentation ist:
vollständig
präzise und
klar
Der traditionelle Ansatz bei der Dokumentation von Entwicklungsprozessen, die dem Wasserfallmodell folgen sieht vor, dass Mitarbeiter in der Endphase des Projekts alle wichtigen Informationen schriftlich festhalten. Die Autoren sammelten alle Dokumente, welche die Entwickler und Manager während der Arbeit am Projekt erstellt hatten und überführte dann diese Notizen, Diagramme, Menüs, Beschreibungen und Details in eine fertige und ausgefeilte Dokumentation, die mit dem Produkt gemeinsam ausgeliefert wurde. Die Dokumentation war somit ein Schritt, der zwischen Abschluss des Projekts und Veröffentlichung eingeschoben wurde.
Leider funktioniert das bei der agilen und iterativen Softwareentwicklung nicht mehr.
Dokumentation von DevOps-Projekten
Bei einem agilen Ansatz stellen Entwickler in manchen Fällen bereits nach wenigen Wochen oder Tagen eine erste Iteration bereit. Ihr folgen weitere Versionen, um Fehler zu beheben, Funktionen hinzuzufügen und Änderungswünsche von Kunden und Vorgesetzten aufzunehmen. Diese Releases liegen ebenfalls oft nur wenige Tage oder Wochen auseinander. Jeden davon müssen Projektmitarbeiter angemessen dokumentieren, um Benutzer, Entwickler, Administratoren und Führungskräfte zu unterstützen.
Die Schnelllebigkeit von DevOps-Projekten setzt technische Redakteure oder Entwickler, die ihre eigene Dokumentation erstellen, unter enormen Druck, wenn sie während des gesamten Projektlebenszyklus eine qualitativ hochwertige Wissenssammlung liefern und pflegen sollen. Das Ergebnis ist oft eine minderwertige Dokumentation, die nicht den genannten Qualitätsmerkmalen entspricht. Häufig kommt es zu folgenden Problemen:
Beim Arbeiten unter Zeitdruck passiert es, dass Autoren wichtige Funktionen übersehen – insbesondere sekundäre oder unterstützende. Benutzer wissen dann nicht, dass es diese Funktion überhaupt gibt, oder wie sie diese verwenden sollen.
Beschreibungen können fehlerhafte Informationen enthalten, zum Beispiel Tippfehler im Beispielcode oder falsche Darstellungen von Syntax oder Argumenten. In Dateipfade und Variablen schleichen sich ebenfalls leicht Flüchtigkeitsfehler ein und Workflows werden möglicherweise nicht korrekt beschrieben.
Manchmal leidet auch die Verständlichkeit der Beschreibungen und Beispiele. Im Idealfall sollte die Dokumentation durch mehrere Hände wandern, um sicherzustellen, dass der Text auch für Außenstehende informativ ist.
Die genannten Schwierigkeiten können die Einführung einer neuen Version verlangsamen oder unnötige Helpdesk-Tickets nach sich ziehen – sowohl von Anwendern, die mit der Software alleine nicht zurechtkommen, als auch von Administratoren, die Nutzern aufgrund mangelnder Informationen selbst nicht helfen können.
Vorgehensweise bei der Dokumentation in DevOps
Unternehmen und Softwareteams müssen ihre Prozesse überarbeiten, um die Herausforderungen bei der Dokumentation trotz DevOps und anderer agiler Entwicklungsparadigmen zu bewältigen.
Die folgenden vier Prinzipien können Ihnen dabei helfen:
1. Dokumentieren Sie früh und oft.
Während traditionell die Dokumentation zu den letzten Schritten eines Projekts gehörte, muss die DevOps-Dokumentation laufend Teil des Entwicklungsprozesses sein. Das ermöglicht es Autoren, während der Programmierarbeit und Tests den aktuellen Zustand des Produkts zu dokumentieren, einschließlich seiner Funktionen, Beispiele, Referenzen, Fallstudien und anderer Anleitungen.
Bei jeder Iteration überarbeiten sie die Dokumentation, um Änderungen und Aktualisierungen vorzunehmen sowie neue Inhalte hinzuzufügen, um den neuesten Stand widerzuspiegeln. Kurz gesagt, Dokumentation sollte den gleichen Projektwert haben wie Codieren und Testen.
2. Beschäftigen Sie Autoren mit technischen Kenntnissen.
Die Pflege der Dokumentation in einer DevOps-Umgebung erfordert eine hohe Geschwindigkeit und Agilität. Es ist wichtig, dass an der Dokumentation Personen beteiligt sind, welche die Funktionsweise des Produkts selbst verstehen können.
Während traditionell die Dokumentation zu den letzten Schritten eines Projekts gehörte, muss die DevOps-Dokumentation laufend Teil des Entwicklungs-Prozesses sein.
Heutzutage sollten die Autoren der Dokumentation sich das Produkt selbst aneignen und es in der Praxis ausprobieren. Im Idealfall haben diese Mitarbeiter eigene Programmierkenntnisse, um Beispiel-APIs zu schreiben sowie Workflow-Kenntnisse, um die wichtigsten Schritte zu skizzieren; und einige Architekturkenntnisse, um akkurat wiedergeben zu können, wie das Produkt funktioniert.
3. Ziehen Sie technisches Personal für die Aufgabe mit heran.
Schreiben die Entwickler nicht selbst die Dokumentation, sollten Sie dafür sorgen, dass die Autoren viele Möglichkeiten zur Kommunikation und Zusammenarbeit mit den technischen Mitarbeitern erhalten. Wenn keine dedizierten technischen Redakteure verfügbar sind, können leitende Entwickler und Projektmanager Dokumentationsaufgaben mit übernehmen.
Es empfiehlt sich immer, die Arbeit auf mehrere Personen aufzuteilen.
4. Finden Sie ein Format, das für Sie funktioniert.
Zeit ist Geld. Übliche Formate für die Dokumentation – wie umfangreiche PDFs und Benutzerhandbücher – sind für eine agile Entwicklungsumgebung ungeeignet oder sogar unmöglich. Unternehmen wenden sich zunehmend flexibleren und durchsuchbaren Formaten zu, die einfacher zu erstellen und zu warten sind. Dafür setzen sie beispielsweise auf Wikis oder Wissensmanagementplattformen. Einige Produkte in diesem Bereich können die Aktualisierung der Dokumentation automatisieren, wenn sich Code oder Funktionen ändern.
Best Practices für die Dokumentation bei DevOps
Sobald Sie sich entschieden haben, Ihren Dokumentationsprozess anzupassen, helfen Ihnen die folgenden fünf Grundsätze:
Brechen Sie Silos auf. Mitarbeiter, die mit der Dokumentation betraut sind, sollten als normale und wesentliche Mitglieder jedes Entwicklungsteams gelten. So wie Entwickler meistens Teil verschiedener Projekte im Unternehmen parallel sind, können Autoren auch über Team- und Projektlinien hinweg wechseln, um bei mehreren Projekten zu helfen.
Fördern Sie die Zusammenarbeit. Kommunikation ist in agilen Umgebungen elementar. Autoren benötigen bei Bedarf schnell Zugriff auf Notizen und das Wissen von Entwicklern und anderen Beteiligten, um effizient arbeiten zu können. Dafür eignen sich beispielsweise regelmäßige Teammeetings oder das Einbinden in Test- und Validierungsprozesse. Je mehr die Autoren über ein Produkt und seine Funktionsweise wissen, desto besser können sie es dokumentieren.
Setzen Sie klare Erwartungen. Jedes Softwareprojekt ist anders und daher unterliegt jede Dokumentation anderen Prioritäten. Wenn Sie die Anforderungen für ein Projekt festlegen, dann gehören dazu auch die notwendigen Inhalte der Dokumentation: Referenzen, Beispiele, Anwendungsfälle, User Stories und Anleitungen. Auf diese Weise verschwenden Autoren ihre Zeit nicht auf das Verfassen nebensächlicher Texte und können ihre Arbeit besser vorbereiten und planen.
Legen Sie Standardwerkzeuge fest. Von Microsoft Word bis hin zu Wikis gibt es unzählige Tools und Plattformen, die sich zum Erstellen einer Dokumentation eignen. Die Wahl der Tools kann sich je nach Projekt und den individuellen Anforderungen von Kunden unterscheiden; es ist dennoch sinnvoll, im Vorfeld eine Auswahl an Standard-Tools bereitzustellen.
Prüfen Sie, welche Schritte Sie automatisieren können. Einige Tools verfügen über Funktionen, die Teile des Dokumentationsprozesses automatisieren. Wenn Sie beispielsweise einen neuen Funktionsaufruf zu einer API hinzufügen, reicht die Software ihn automatisch zum Abschnitt der Dokumentation mit Referenzen und Beispielen weiter. Das stellt sicher, dass keine Änderungen übersehen werden und keine Fehler beim Kopieren unterlaufen. Wenn Sie Automatisierung verwenden, dann müssen Sie diese auf jeden Fall wiederum dokumentieren.
Es gibt keine einfache Lösung
Es gibt keinen Standardansatz für DevOps oder andere agile Projektdokumentationen. Frühe Versuche, die Dokumentation zu standardisieren, wie Open Source DocOps, haben sich nie wirklich durchgesetzt. Dokumentationsziele und inhaltliche Anforderungen variieren viel zu sehr für eine Standardlösung, abhängig von der Branche, vom Umfang des Projekts, der Unternehmenskultur und der Vereinbarungen mit dem einzelnen Kunden.
So unterscheidet sich die Dokumentation für ein Computerspiel stark von der Dokumentation einer industriellen Softwareplattform. Dokumentationen verleihen einem Softwareprojekt immer noch Qualität und Wert – solange sie in der Lage sind, Schritt zu halten und die Herausforderungen agiler Umgebungen zu bewältigen.
