Docs-as-Code – Redaktionsverfahren aus der Softwarebranche

Docs-as-Code als Redaktionsverfahren

Docs-as-Code ist eine Methode zur Erstellung von Softwaredokumentation. Im Wesentlichen werden bei Docs-as-Code die Werkzeuge aus der Softwareentwicklung verwendet. Dazu gehören eine git-basierte Dateiverwaltung, eine umfassende Automatisierung, ein kollaborativer Review-Prozess und „leichtgewichtige“ Auszeichnungssprachen. Das heißt, reine Textdateien werden so markiert, dass sie strukturelle Informationen und Layoutanweisungen enthalten. Einige der im Allgemeinen bekanntesten Auszeichnungssprachen sind HTML und XML. Hier werden die Inhalte durch eine Reihe von Anweisungen in spitzen Klammern, sogenannten „Tags“, strukturiert. Bei den Auszeichnungssprachen für Docs-as-Code (z. B. AsciiDoc, reStructured Text oder Markdown) gibt es keine Tags, die Markierung erfolgt durch Sonderzeichen.

Docs-as-Code im Einsatz

Bei Docs-as-Code integriert sich die Technische Redaktion in die Toolchain der Softwareentwicklung. Inhalte werden in Editoren wie Visual Studio Code, IntelliJ IDEA oder dem Markdown Pad erstellt, wobei im Prinzip aber jeder Text-Editor verwendet werden kann. Für die Contentverwaltung mit einer Docs-as-Code-Toolchain nutzen Redakteure sogenannte Repositories. Dort liegen die Quelldateien dann entweder zusammen mit dem Softwarecode in einem Repository oder werden getrennt vom Softwarecode in einem eigenen Repository für die Dokumentation gepflegt. Bekannte Plattformen zur git-basierten Verwaltung von Inhalten in Repositories sind GitHub, Bitbucket oder GitLab. Für die Endnutzer lassen sich die Inhalte der Quelldateien dann durch Transformationen als HTML oder PDF bereitstellen. Dafür kommen Werkzeuge wie Antora, Sphinx, Hugo oder Jekyll zum Einsatz.

Die Kernelemente einer Docs-as-Code-Toolchain lassen sich recht flexibel miteinander kombinieren. Welche Werkzeuge gewählt werden, hängt davon ab, in welcher Umgebung die Softwareentwicklung stattfindet und wie sich die Zusammenarbeit im Team bestmöglich herstellen lässt. Oft wird die konkrete Auswahl der Werkzeuge später noch ergänzt durch Skripte, um zum Beispiel Abläufe zu automatisieren.

Docs-as-Code: Chancen und Risiken

Redaktionen, die die Arbeit mit einem CCMS gewohnt sind, wird Docs-as-Code zunächst wohl ein wenig fremd vorkommen. Allerdings bietet dieses Verfahren einige Vorteile. Der Wichtigste ist wohl, dass Softwareentwicklung und Technische Dokumentation leicht Hand in Hand laufen können, weil beide dieselben Tools verwenden. Im Gegensatz zu CCMS-Daten sind die Docs-as-Code-Dokumente für jeden nutzbar, der die Zugriffsberechtigungen dafür besitzt; es ist kein Zugang zu einem Spezialsystem notwendig. Anders als bei XML-Dateien sind die bei Docs-as-Code angewandten Auszeichnungssprachen vergleichsweise flüssig von Menschen lesbar – ein Vorteil, wenn man sich einen schnellen Überblick über die Inhalte verschaffen möchte.

Diese Vorteile bedeuten für die Redaktion allerdings oft den Verzicht auf Konzepte und Arbeitsweisen, die die moderne Technische Dokumentation zu schätzen gelernt hat. Wiederverwendung von Inhalten oder die Integration von Bild- und Grafikbearbeitung sind zwar möglich, aber vielleicht nicht ganz so komfortabel wie in manchen CCMS. Insbesondere für die Metadaten-Verwaltung, zum Beispiel um Inhalte im Anschluss an Content-Delivery-Portale weiterzugeben oder um mit Ontologien zu arbeiten, gibt es aktuell noch keine ausgereiften Lösungen. Auch die Einbindung von Produktdaten aus weiteren Systemen, zum Beispiel PIM-Systemen, ist aktuell noch nicht verbreitet.

Docs-as-Code spielt seine Vorteile aus, wenn es um die nahtlose Integration der Technischen Redaktion in die Entwicklungsteams geht. Dies ist insbesondere hilfreich, wenn auch Entwickler Inhalte für die Dokumentation beitragen. Durch die Nutzung gemeinsamer Werkzeuge, durch das ganz selbstverständlich gelebte Vier-Augen-Prinzip mittels effizienter, komfortabler Review-Prozesse und durch die Automatisierung verschiedener Schritte in der Dokumentationsbereitstellung kann die Dokumentation in genauso kurzen Zyklen kontinuierlich aktualisiert und publiziert werden wie die Software. Docs-as-Code wird daher immer häufiger von Entwicklungsabteilungen als Methode in der Technischen Dokumentation gewünscht. Technische Redaktionen sollten aber dennoch genau analysieren, ob der Vorteil einer engeren Anbindung an das Entwicklungsteam die Einschränkungen in der Redaktionsarbeit rechtfertigt.