In der Softwareentwicklung läuft manches anders als in anderen Branchen. Die Entwicklungsprozesse sind agil und iterativ, die Hierarchien flach und die Entwicklungsteams klein und weitgehend selbstorganisiert. Es ist daher nicht verwunderlich, dass sich auch die Art und Weise, wie Softwareunternehmen Dokumentation erstellen, von der in anderen Wirtschaftszweigen unterscheidet. Hier kommt Docs-as-Code ins Spiel
Der Docs-as-Code-Ansatz integriert die Dokumentationserstellung in die Arbeitsabläufe der Softwareentwicklung, um eine kontinuierliche Entwicklung und Bereitstellung zu unterstützen. Die Verantwortung für die Dokumentation liegt dabei nicht bei einer separaten Technischen Redaktion, sondern beim Team. Konsequenterweise tragen alle Teammitglieder Inhalte bei oder erstellen zumindest Entwürfe zur weiteren Bearbeitung. Die Zusammenarbeit erfolgt dabei über ein gemeinsames „Repository“, in dem alle Quelldateien der Software, also Programmcode und Dokumentationsinhalte, zentral verwaltet werden.
Die verwendeten Dokumentationswerkzeuge orientieren sich an der Denk- und Arbeitsweise von Softwareentwicklern, damit sie sich nahtlos in deren Arbeitsabläufe einfügen und akzeptiert werden. Redaktionssysteme sind in diesem Umfeld weniger geeignet, da sie sich meist nicht so gut in Softwareentwicklungsprozesse integrieren lassen und somit Automatisierungspotenziale nicht genutzt werden können. Hinzu kommt, dass Softwareentwickler die von ihnen verwendeten Tools oft an spezifische Anforderungen anpassen und Verbesserungen gerne mit anderen Nutzern im Unternehmen oder in der Community teilen. Aus diesem Grund bevorzugen sie oft Open-Source-Werkzeuge. Grundsätzlich ist Docs-as-Code unabhängig von bestimmten Werkzeugen und damit auch unabhängig von einzelnen Herstellern.
Die Funktionsweise von Docs-as-Code
Das Grundprinzip von Docs-as-Code ist denkbar einfach. Denn es besagt im Grunde nichts anderes, als dass die Dokumentation mit den gleichen Werkzeugen erstellt und verwaltet wird wie der Softwarequelltext. Docs-as-Code ist somit nicht als genau definierter „Werkzeugkasten“ zu verstehen, sondern eher als eine Methode zur Dokumentationserstellung. Sie definiert einige wenige Grundprinzipien und lässt den Anwendern größtmögliche Freiheiten bei der Umsetzung. In den nächsten Absätzen erläutere ich die Funktionsweise des Prinzips an einem Beispiel.
Texte werden in einem reinen Textformat mit einem beliebigen Texteditor geschrieben. Entwickler verwenden meist die Entwicklungsumgebung, in der sie auch ihren Programmcode erstellen, also zum Beispiel PyCharm in der Python-Welt. Andere häufig verwendete Editoren sind Notepad++ (nur Windows) und Visual Studio Code (plattformübergreifend). Prinzipiell funktioniert aber jedes Programm, das reine Textdateien bearbeiten kann, also auch die mit dem jeweiligen Betriebssystem mitgelieferten Editoren. Die Dateien werden zusammen mit dem Softwarequelltext im Versionsmanagementsystem (heutzutage meist „Git“) verwaltet. Autoren profitieren dabei vom Versionsmanagementsystem, das ausgefeilte Funktionen für Versionierung, paralleles Arbeiten in „Branches“ oder asynchrone Reviewprozesse mitbringt.
Analog zum „Bauen“ der lauffähigen Software kümmert sich ein darauf spezialisiertes Programm darum, die Textinhalte in das gewünschte Ausgabemedium zu konvertieren. Beispiele hierfür sind Asciidoctor, Sphinx oder Antora. Diese Programme erzeugen neben den konvertierten Inhalten auch eine Navigationsstruktur, Querverweise oder einen durchsuchbaren Index. Die so erstellten Publikationen können dann bei Bedarf weiterverarbeitet werden. Enterprise-Software von CONTACT enthält zum Beispiel ein eigenes integriertes Content-Delivery-Portal (Abb. 01), das die Dokumentationsinhalte den Anwendern zur Verfügung stellt. Docs-as-Code bietet also sehr viele Freiheiten bei „Make or Buy“-Entscheidungen hinsichtlich der verwendeten Softwarekomponenten.
Durch die enge Verzahnung mit den Werkzeugen und Prozessen der Softwareentwicklung ermöglicht Docs-as-Code einen hohen Automatisierungsgrad. So können zum Beispiel automatische Tests zur Qualitätssicherung eingesetzt werden. Zudem kann bei der Erstellung der Dokumentation auf das Wissen der Teammitglieder im Hinblick auf Automatisierung und geschickte Verknüpfung der vorhandenen Tools zurückgegriffen werden. Dieses Wissen steht in einer Technischen Redaktion normalerweise nicht oder nicht in vergleichbarer Tiefe zur Verfügung.
Abb. 01 Inhalte entstehen nach Docs-as-Code und werden in einem Content-Delivery-Portal dargestellt. Quelle Hans-Jörg Elsen
Werkzeuge für die Strukturierung
Ähnlich bunt und vielfältig wie die Tool-Landschaft der Softwareentwickler ist die Auswahl bei den Werkzeugen für Docs-as-Code. Bei CONTACT Software kommt die in der „klassischen“ Technischen Dokumentation sicherlich weniger bekannte Software Sphinx in Verbindung mit der Auszeichnungssprache reStructuredText zum Einsatz (Abb. 02).
Sphinx ist ein „Documentation Generator“, der im Umfeld der Programmiersprache Python entstanden ist und eine Vielzahl von Ausgabeformaten erzeugen kann. Zudem lässt sich Sphinx gut in die eigene Entwicklungsumgebung integrieren und erleichtert dadurch die Automatisierung des Publikationsprozesses. Die Auszeichnungssprache reStructuredText ist leicht zu erlernen und gut zu lesen, so dass man sich schnell zurechtfindet. Für die Entwicklungsdokumentation ist außerdem interessant, dass Python-Elemente direkt im Quelltext dokumentiert und automatisch extrahiert werden können.
Abb. 02 Aus den Quelldateien entstehen mit Hilfe des Documentation Generators die gewünschten Ausgabeformate. Quelle Hans-Jörg Elsen
Textauszeichnung mit reStructuredText
Ähnlich wie die verbreiteten Auszeichnungssprachen Markdown und Asciidoc arbeitet reStructuredText mit einfachen Konventionen wie zum Beispiel Leerzeilen und Unterstreichungen, um Absätze oder Abschnitte zu kennzeichnen. Darüber hinaus bietet reStructuredText zwei syntaktische Konzepte. Diese ermöglichen es, den Sprachumfang von reStructuredText zu erweitern, so dass im Laufe der Zeit die Zahl der Auszeichnungselemente wächst und eine spezifischere semantische Beschreibung von Inhalten ermöglicht: „Directives“ erlauben die Auszeichnung von Inhaltsblöcken mit spezifischen Bedeutungen. Warnhinweise lassen sich zum Beispiel mit den Directives „.. danger::“, „.. warning::“ und „.. caution::“ abbilden. In der Softwaredokumentation sind diese Hinweise allerdings seltener erforderlich als in anderen Branchen. Daher greift man hier eher zu einfachen Hinweisen wie in Abbildung 03.
Abb. 03 Semantische Auszeichnung am Beispiel eines einfachen Hinweises. Quelle Hans-Jörg Elsen
Ein für die Softwarebranche typisches Beispiel zeigt Abbildung 04 mit einem Code-Schnipsel und dessen Darstellung in der Publikation. Die zugehörige Directive „.. code-block::“ kann über Optionen weiter gesteuert werden. In unserem Beispiel werden Zeilen nummeriert und die Zeilen 3 und 5 optisch hervorgehoben.
Abb. 04 Code-Schnipsel und dessen Darstellung in der Publikation. Quelle Hans-Jörg Elsen
Mit „Roles“ können Autoren einzelne Textteile auszeichnen, um diese zum Beispiel semantisch zu kennzeichnen. Diese Textteile können dann entsprechend ihrer Auszeichnung weiterverarbeitet werden. Abbildung 05 zeigt zwei Beispiele: Zum einen die „:kbd:“-Role, mit der Tastatureingaben gekennzeichnet werden. Im CONTACT-Dokumentationsportal werden diese in einer anderen Schrift sowie grau hinterlegt dargestellt. Zum anderen die „:menuselection:“-Role, mit der eine Menüauswahl semantisch ausgezeichnet wird. Trennzeichen zwischen den einzelnen Menüeinträgen werden vom CONTACT-Dokumentationsportal auf der Grundlage des Markups automatisch eingefügt. „Roles“ und „Directives“ können auch zusammenwirken: So baut man mit der „.. glossary::“-Directive ein Glossar auf, um anschließend mit der „:term:“-Role von beliebigen Stellen in der Dokumentation auf Glossareinträge verweisen zu können.
Abb. 05 Grau Hinterlegt sind "Roles"; mit dieser Kennzeichnung lassen sich bestimmte Funktionen und Eigenschaften zuordnen. Quelle Hans-Jörg Elsen
Die Vor- und Nachteile
Aus den einfachen Grundprinzipien von Docs-as-Code zum Verwenden von Textdateien für die Erstellung der Inhalte und Integration in die Softwareentwicklungsumgebung ergeben sich mehrere Vorteile:
- Die Inhalte werden getrennt vom Layout erstellt, und durch die Verwendung von Textdateien sind die Inhalte leicht lesbar und unabhängig von bestimmten Werkzeugen oder Herstellern. Im Vergleich zu Binärdateien belegen sie sehr wenig Speicherplatz und können mit den in den Versionsmanagementsystemen vorhandenen Funktionen zum Textvergleich leicht verglichen werden. Dies erleichtert die Integration in die Review-Prozesse des Produktentwicklungsteams, wodurch die Dokumentation sich nahtlos in die agile, iterative Arbeitsweise einfügt.
- Das Layout wird komplett automatisch erzeugt, so dass sich die Autoren auf die Inhalte konzentrieren können. Layoutanpassungen erfolgen zentral durch Änderung der Konvertierungsregeln. Da für die Publikation im Normalfall etablierte Technologien wie HTML oder PDF verwendet werden, steht eine große Auswahl von Werkzeugen zur Weiterverarbeitung zur Verfügung. Zudem ist man nicht von hochspezialisierten Experten abhängig, da das notwendige Wissen in der Regel bereits im Team vorhanden ist.
- Die für die Dokumentationserstellung erforderliche Softwareumgebung ist preiswert oder in den meisten Fällen sogar kostenlos. Viele Komponenten sind frei und quelloffen verfügbar. Dadurch ist Docs-as-Code auch für kleine Unternehmen interessant, da in der Regel keine externen Kosten für die Anschaffung und Anpassung von Dokumentationssystemen anfallen. Zudem sind Textauszeichnungssprachen wie reStructuredText leicht zu lernen, insbesondere im Vergleich zu komplexen Informationsarchitekturen wie DITA.
Auf der anderen Seite stehen folgende Nachteile:
- Docs-as-Code verwendet wegen der leichten Erlernbarkeit Markup-Sprachen wie zum Beispiel das bereits vorgestellte reStructuredText. Die Sprachen sind zwar weniger restriktiv als XML-basierte Informationsarchitekturen wie DITA, können aber weder formal validiert werden noch strukturelle Vorgaben machen. So ist es zum Beispiel nicht möglich, in aufgabenorientierten Inhalten („Tasks“ in DITA) Schritt-für-Schritt-Anleitungen zu erzwingen. Zudem gibt es keine komplexeren hierarchischen Elemente wie zum Beispiel das DITA-Element „hazardstatement“. Zudem fehlen formal definierten Topic- Typen. Strukturelle Vorgaben für den Inhalt müssen also redaktionell- organisatorisch umgesetzt werden.
- Docs-as-Code bietet naturgemäß kein „What you see is what you get“. Um die erstellten Inhalte im Ganzen anschauen zu können, muss man eine lokale Vorschauansicht erzeugen. Manche Umgebungen können die Voransicht in Echtzeit bereitstellen. Allerdings kann die Ansicht mehr oder weniger stark vom endgültigen Publikationslayout abweichen, wenn man zum Beispiel ein eigenes Content-Delivery-Portal einsetzt. Werkzeuge aus der Tradition des Desktop Publishings oder der klassischen Textverarbeitung wie Microsoft Word, Adobe FrameMaker oder InDesign erlauben flexible Layouts, die bei Docs-as-Code nicht möglich sind. Das liegt an der Layoutautomatisierung, die prinzipbedingt auf die Verarbeitung der vorgegebenen Markup-Elemente beschränkt ist. Komplexe und aufwändige Layouts sollten möglichst nicht erforderlich sein, da diese meist nicht vollständig automatisch aus den Textauszeichnungen abgeleitet werden können. Eine aufwändige manuelle Nachbearbeitung steht der Docs-as-Code-Idee fundamental entgegen.
Topics und Wiederverwendung
In der Technischen Dokumentation sind Modularisierung, Wiederverwendung und Variantenmanagement wichtige Methoden, um effizient und zuverlässig mit großen Informationsmengen umzugehen. Sphinx und reStructuredText unterstützen diese Methoden mit verschiedenen Techniken. So können zum Beispiel Dateien in andere eingebunden werden, so dass sich die Inhalte an verschiedenen Stellen wiederverwenden lassen. Darüber hinaus gibt es Variablen, die für kürzere Inhalte geeignet sind, also zum Beispiel für Produktnamen oder Grafiken, die an einer zentralen Stelle verwaltet werden. Diese Konzepte sind aber nicht so ausgefeilt wie etwa das Content-Reuse-Konzept in DITA oder die datenbankbasierten Funktionen in modernen Redaktionssystemen. Sie dienen eher dazu, es den Softwareentwicklungsteams zu erleichtern, ihre Dokumentation nahe beim Softwarequelltext zu erstellen und zu verwalten.
Übersetzung der Inhalte
Auch bei der Übersetzung wird bei CONTACT der Docs-as-Code-Ansatz konsequent umgesetzt, wie sich am Beispiel von reStructuredText und Sphinx zeigen lässt. Um reStructuredText-Quelldateien übersetzen zu können, wird für jede Quelldatei eine Datei im so genannten „.PO“-Format mit Textsegmenten für die Übersetzung erzeugt. Die PO-Dateien enthalten für jedes Segment einen Eintrag für die Ausgangssprache und einen (zunächst leeren) Eintrag für die Zielsprache, die während der Übersetzung befüllt werden. Sphinx nutzt dann diese PO-Dateien zur Erzeugung der zielsprachlichen Publikation. Da die Transferdateien für die Übersetzung ebenfalls reine Textdateien sind, können sie ebenso wie die reStructuredText-Quellen im Versionsmanagementsystem verwaltet werden. Die Übersetzung kann dadurch kontinuierlich und iterativ erfolgen. Da alle Beteiligten im gleichen Repository arbeiten, kann der Übersetzungsprozess wie die Dokumentationserstellung in die Entwicklungsabläufe integriert werden.
Bei CONTACT kommt zudem das Translation-Management-System „Weblate“ zum Einsatz, das sich sehr gut für Docs-as-Code-Umgebungen eignet. Weblate integriert sich vollständig in das weitverbreitete Versionsmanagementsystem „Git“, so dass es ohne Medienbrüche in die Entwicklungsumgebung des Produktentwicklungsteams eingebunden werden kann und einen kontinuierlichen Übersetzungsprozess unterstützt. Da Weblate browserbasiert arbeitet, benötigen die Anwender keine lokale Softwareinstallation und arbeiten automatisch alle mit der gleichen Version. Übersetzungsaufgaben werden in Projekten organisiert, denen interne wie externe Anwender, also zum Beispiel Mitarbeiter eines Übersetzungsdienstleisters, mit unterschiedlichen Rechten zugeordnet werden. Dadurch lässt sich die Mitarbeit der einzelnen am Übersetzungsprozess beteiligten Teammitglieder differenziert steuern.
Für Weblate existieren unterschiedliche Nutzungsmodelle. Man kann die Open-Source-Software kostenlos oder mit einem kostenpflichtigem Wartungsvertrag im eigenen Unternehmen betreiben oder alternativ als Cloud-Dienst nutzen, bei dem man sich nicht um den laufenden Betrieb kümmern muss. Neben den Kosten und dem Wartungsaufwand spielt bei der Entscheidungsfindung auch eine Rolle, wie stark Übersetzer in das Entwicklungsteam eingebunden sein sollen und wie kontinuierlich die Zusammenarbeit sein soll.
Und die Technische Redaktion?
Docs-as-Code wirkt auf viele Technische Redakteure zunächst ungewohnt. Doch kann sich der Blick über den Tellerrand für den einen oder anderen lohnen: Bei Docs-as-Code gibt es im Normalfall keine Dokumentationsabteilung. Stattdessen ist man als Redakteur Teil des Produktentwicklungsteams und dadurch besser in die Produktentwicklung integriert. Potenziell können alle Teammitglieder Dokumentationsinhalte beitragen. Als Dokumentationsexperte nimmt man daher häufig auch eine beratende Rolle ein und wirkt konzeptionell bei Prozessverbesserungen mit. Eine willkommene Gelegenheit, die eigenen Kompetenzen über die rein redaktionelle Arbeit hinaus einzubringen und auszubauen. Wer gerne an der kontinuierlichen Verbesserung der Dokumentations-„Toolchain“ mitwirkt und kreativ die verwendeten Tools ausreizt, ist bei Docs-as-Code an der richtigen Stelle. Dabei kann man vom Know-how der Entwicklerkollegen profitieren und für die Automatisierung von Dokumentationsprozessen nutzbar machen. Software ist allgegenwärtig und in unterschiedlichen Ausprägungen mittlerweile in vielen Produkten enthalten. Der Bedarf an Softwaredokumentation nimmt also zu. Wer Spaß an Software hat und enger mit Softwareentwicklern zusammenarbeiten möchte, sollte daher Docs-as-Code einfach ausprobieren.
Ein hohes Maß an Integration
Es ist sicherlich kein Zufall, dass die Docs-as-Code-Idee in der Softwarebranche entstanden ist. Schließlich haben sich in dieser Branche iterative Entwicklungsmethoden durchgesetzt, die auf kontinuierliche Integration und automatisierte Auslieferung von Softwareänderungen setzen. Da erscheint es nur logisch und konsequent, die Dokumentationserstellung und redaktionelle Prozesse so weit wie möglich in die Softwareentwicklung einzubetten. Zudem ist es naheliegend, Technische Redakteure genauso ins Team zu holen wie alle anderen Fachexperten. Der Docs-as-Code-Ansatz ist dabei nicht auf Softwaredokumentation beschränkt, jedoch spielt er seine Stärken vor allem bei der Dokumentation von digitalen Produkten aus, bei denen es regelmäßige, inkrementelle Änderungen gibt und die Dokumentation mit dem Produkt zusammen „gebaut“ und bereitgestellt werden soll.
Dies sind in der Regel Produkte, die nach „agilen“ Prinzipien entwickelt werden und deren Nutzungsinformation ebenfalls eher digital genutzt werden.
Links
https://www.sphinx-doc.org
https://www.weblate.org
https://antora.org
https://asciidoctor.org
https://asciidoc.org
