Docs-as-Code - klingt nur kompliziert

Text: Petra Herbst

In letzter Zeit hört man immer wieder das Schlagwort „Docs-as-Code“. Wer nicht in der Software­entwicklung tätig ist, kann damit wenig anfangen – auf den ersten Blick. Denn Docs-as-Code kann dazu beitragen, die Softwaredokumentation zu vereinfachen.

Inhaltsübersicht

Lesedauer: 08:48 Minuten

Zu Beginn eine Begriffsdefinition, wobei sich Docs-as-Code fast von selbst erklärt: Dokumentation (Docs) wird gleichbehandelt wie Programmiercode (Code) und so weit wie möglich automatisiert. Der naheliegende Anwendungsbereich für Docs-as-Code ist somit die Softwaredokumentation, nachdem bei der Softwareentwicklung die gleichen Werkzeuge, Verfahren und Methoden zum Einsatz kommen wie bei Docs-as-Code. Allerdings ist es genauso möglich, jede andere Art von Technischer Dokumentation anstatt mit einem Autorensystem oder in einem Wiki in einer Markdown-Sprache zu verfassen, wie zum Beispiel ASCIIDOC¹, und dann mittels einer Open-Source-Software in jedes beliebige Zielformat zu bringen, wie etwa Asciidoctor². 

Grundsätzlich ist Automatisierung etwas für faule Menschen, weil viele sich ständig wiederholende Aufgaben der Computer übernimmt und Dinge erledigt, die man vorher selbst durchführen musste (Abb. 01). Dadurch haben die Technischen Redakteurinnen und Redakteure wieder mehr Kapazitäten frei für andere Tätigkeiten wie etwa Pair-Documenting oder Coaching der Dokumentationsersteller, die keinen Hintergrund oder nur wenig Erfahrung beim Schreiben von Dokumentation haben.

Ablaufschema von Docs-as-Code.

Abb. 01 Mit Docs-as-Code lässt sich vernetzt und auto­matisiert arbeiten. Quelle Petra Herbst

Die wesentlichen Komponenten

Unter Docs-as-Code fallen grundsätzlich alle Programme, die dabei behilflich sind, den Dokumentationserstellungsprozess zu vereinfachen und zu automatisieren. Welche Programme sind nötig, um damit eine Docs-as-Code-Werkzeugkette zu erzielen? Die Hauptkomponenten, die bei Docs-as-Code zum Einsatz kommen, können wie folgt zusammengefasst werden:

  • Textdateien (Markup³, Markdown⁴ im Unterschied zu binären Dateiformaten wie etwa in Adobe FrameMaker oder Microsoft Word)
  • Texteditor wie etwa Atom oder Sublime Text
  • Statischer Seiten-Generator⁵, meist Open-Source, wie etwa Sphinx, Jekyll oder Hugo
  • Speichern aller Komponenten in einem Versionskontrollsystem⁶, meist git
  • Zusammenarbeit erfolgt auch über git⁷ (branch, merge, push)
  • CI/CD⁸ zur Automatisierung des „Bauens“ (Build⁹) und Publizierens (Deployment¹⁰) der Zieldateien auf der Zielplattform
  • Automatisierte Tests (Link-Checker, Formatierungen, Terminologie)

Die meisten dieser Komponenten sind in einer Softwarefirma bereits vorhanden und es gibt noch genug freie Lizenzen. Oder es ist meist mit wenig bürokratischem Aufwand möglich, diese zu bekommen. Allerdings gilt es dann, diese Werkzeuge in der richtigen Reihenfolge zu benutzen, und dabei ist es ratsam, auf das Expertenwissen innerhalb der Firma zurückzugreifen.

Jedes Softwareunternehmen hat seine eigene Art und Weise, Quellcode zu verwalten und Code zu produzieren. Deshalb ist es am einfachsten, sich mit den Entwicklern abzustimmen und dieses meist hausinterne Wissen anzuzapfen. Erstens erlangt man so einen guten Überblick (vor allem, wenn man nicht nur einen einzigen Entwickler befragt), welche Komponenten bereits im Haus vorhanden sind. Und zweitens bekommt man ein Gefühl dafür, wer Interesse daran haben könnte, sich an einer Umstellung der Dokumentationserstellung auf Docs-as-Code zu beteiligen.

Meistens sind auch Vorgesetzte Änderungen gegenüber aufgeschlossener, wenn diese die Ziele haben, Werkzeuge mehrfach einzusetzen, Arbeitsweisen zu vereinfachen und wiederzuverwenden. Darüber hinaus bleibt noch zu erwähnen, dass der Markt zahlreiche Open-Source-Software anbietet, mit der man gut arbeiten bzw. auch einen PoC (Proof of Concept) bewerkstelligen kann.

Kurzfristig bedeutet so eine Umstellung etwas mehr Arbeit für die Entwickler. Schließlich stellt ein Wissenstransfer einen zusätzlichen Zeitaufwand dar. Aber mittelfristig wird den Entwicklern Arbeit abgenommen, denn ihre Standardprozesse kommen auch für die Technische Dokumentation zum Einsatz. Außerdem können sie ganz einfach über ein Plug-in in ihrer Entwicklungsumgebung (IDE¹¹) die Dokumentation schreiben oder anpassen – ohne in ein anderes Programm wechseln zu müssen.

Tabelle mit kurzerklärten Fachwörtern.

Das Gute daran

Das Hauptargument, warum man auf Docs-as-Code umsteigen sollte, ist mit Sicherheit der Zeitfaktor. Besonders im Softwarebereich werden die Releasezyklen immer kürzer, Service Packs werden häufig jede Woche zur Verfügung gestellt, und ohne Automatisierung ist es kaum möglich, jedes Mal eine vollständige und korrekte Dokumentationsversion mit auszuliefern. Wenn dann für die Entwickler oder Technischen Redakteure lediglich das Schreiben der Dokumentation zu tun ist und der Rest wie von Zauberhand erledigt wird, ist es jedoch sehr wohl möglich, eine aktuelle Dokumentation mitzuliefern. Die Erstellung kann jederzeit auf Knopfdruck passieren, besser gesagt mit einem Klick auf den Button.

Neben der Zeitersparnis ist ein weiterer wichtiger Grund die Entwicklerfreundlichkeit und dadurch auch ihre Bereitschaft, die Dokumentation immer sofort zu schreiben. Das wiederum führt zu einer höheren Qualität und schnelleren Verfügbarkeit der Dokumentation, weil sich die Entwickler nicht zusätzlich in die Thematik einarbeiten müssen. Darüber hinaus bringt die Verwendung eines Versionskontrollsystems nicht nur eine einfache Art und Weise der Zusammenarbeit mit sich. Die Technische Dokumentation wird automatisch versioniert und alle Änderungen können jederzeit zurückverfolgt werden.

Zusätzlich lassen sich Inhalte und Formatierung getrennt voneinander warten, zudem können die Inhalte leicht wiederverwendet werden. Eine Modularisierung und die Verwendung von Snippets (dt. Textschnipsel) ist auch beim Schreiben von Programmiercode weit verbreitet.

Als letzter Punkt sei nochmals erwähnt, dass Docs-as-Code-Werkzeugketten meist deutlich günstiger sind im Vergleich zu Wikis oder Autorensystemen, weil eventuell nur zusätzliche Lizenzen für die bereits vorhandenen Werkzeuge angeschafft werden müssen. Außerdem steht Open-Source-Software bereit. Zusammengefasst:

  • Zeitfaktor – jederzeit und auf Knopfdruck innerhalb weniger Minuten eine neue Version der Technischen Dokumentation
  • Entwicklerfreundlichkeit – höhere Qualität, da kein Verlassen der Entwicklungsumgebung notwendig
  • Versionierung und Rückverfolgbarkeit
  • Trennung von Inhalt und Formatierung
  • Wiederverwendbarkeit von Inhalten
  • Preislich günstig, weil viel Open-Source-Software am Markt vorhanden ist.

Und die Nachteile

Der Vollständigkeit halber seien hier einige Nachteile erwähnt. Die Umstellung von etablierten Erstellungsverfahren Technischer Dokumentation auf Docs-as-Code geht leider nicht über Nacht. Sie kostet zudem die Zeit und Arbeitskraft der Beteiligten, meist ein Team von Fachleuten aus Technischer Redaktion und Entwicklung.

Je nach Werkzeug können auch noch die Kosten für die nötigen Komponenten entstehen (sofern noch nicht vorhanden). Falls das Wissen nicht im Haus vorhanden ist, kommt der Aufwand für eine externe Beratung hinzu.

Alternativen sind möglich

Geht es auch anders? Eine verständliche Frage, die mit einem klaren „Ja“ zu beantworten ist. Anstatt sich die einzelnen Komponenten selbst zusammenzusuchen und eine geeignete Werkzeugkette (Toolchain) zu überlegen, kann man auch eine All-in-One-Lösung wählen. Oder man startet mit *.asciidoc und bittet einen Entwickler, die Automatisierung vorzunehmen. Für traditionelle Technische Dokumentation bieten sich etwa Sphinx12 oder Asciidoctor an, für API-Dokumentation auch redocly13.

Der Prozess im Einzelnen

Abbildung 02 stellt linear die einzelnen Schritte im Dokumentationsprozess Docs-as-Code dar. Die Schritte werden im nächsten Abschnitt genauer erläutert.

Übersicht über die Arbeitsschritte.

Abb. 02 Typischer Prozess der Dokumentationserstellung mit Docs-as-Code. Quelle Petra Herbst

Wie in der Softwareentwicklung üblich beginnt der Prozess mit einem „Request“. Meistens teilt der Produktmanager den Technischen Redakteuren mit, dass sich die Software geändert hat und deshalb auch die Technische Dokumentation angepasst werden soll. Hierbei sei erwähnt, dass in agilen Umgebungen die Redakteurinnen und Redakteure Teil des Entwicklungsteams sind und es meist keines expliziten Arbeitsauftrags bedarf. Schließlich wissen sie immer, woran gerade gearbeitet wird und welche Dokumentationsänderungen notwendig sind.

1. Schreiben in einem Texteditor oder der IDE¹⁴ ist der erste Schritt, etwa mit dem Editor Atom (Abb. 03). Ob und wie viele „Reviews“ hierbei zum Tragen kommen, hängt von der Arbeitsweise des jeweiligen Teams ab. In der Praxis ist es gängig, dass Technische Redakteure die Rohfassung der Entwickler bearbeiten und die Entwickler dann am Ende die Version der Redakteure nochmals überprüfen.

Screenshoot aus Atom-Editor.

Abb. 03 Beispiel für ein Markdown-Dokument im Atom-Editor. Quelle Petra Herbst

2. Commit im Versionskontrollsystem ist der zweite Schritt (Abb. 04). Commit bedeutet das Einpflegen der Änderungen im Versionskontrollsystem, allerdings noch nicht in die Endversion (master branch¹⁵), sondern vorerst nur lokal (feature branch¹⁶). Dadurch werden die Änderungen unwiderruflich gespeichert, und im Hintergrund wird ein „Merge Request“ (MR) erstellt. Sobald es einen MR gibt, beginnt auch der Build¹⁷ als Teil der CI/CD-Kette zu laufen.

Screenshot aus GitLab.

Abb. 04 Commit der Änderungen im Versionskontrollsystem GitLab. Quelle Petra Herbst

3. CI/CD und Checks sind der dritte Schritt. Hier wird überprüft, ob die Dokumentationsänderungen problemlos in die Endversion (master branch) eingepflegt werden können oder nicht. Wenn weitere Tests, wie das Überprüfen von Links oder Terminologie, konfiguriert wurden, werden diese auch in diesem Schritt (automatisiert) ausgeführt. Das Ergebnis der Tests und des gesamten Builds wird meist bildlich als grün (erfolgreich) oder rot (fehlerhaft) angezeigt. Ist der Build grün und es bedarf keiner weiteren Änderungen mehr, kann der MR jetzt in die Endversion (master branch) gemerged (dt. eingepflegt) werden (Abb. 05). Sobald der dritte Schritt erfolgreich erledigt ist, kommt der letzte Schritt, nämlich das Deployment.

Screenshot aus GitLab.

Abb. 05 CI/CD mit erfolgreichem grünen Build-Status. Quelle Petra Herbst

4. Letzter Schritt: Deployment – hier wird die neue Version der Dokumentation auf der jeweiligen Zielplattform veröffentlicht (Abb. 06). Die Plattform kann ein firmeninterner Server oder auch eine Cloud-Plattform sein. Auch bei den Zielformaten gibt es wenig Einschränkungen. E-Book und PDF sind genauso möglich wie HTML, wobei sich statische HTML-Seiten als Zielformat bewährt haben.

Screenshot aus GitLab und dem Entwicklerportal.

Abb. 06 Ansicht der Quelldateien in GitLab und deployte Version des Entwicklerportals.
Quelle Petra Herbst

Einfach loslegen

Es gibt unendlich viele Möglichkeiten, eine Docs-as-Code-Werkzeugkette umzusetzen. Meist ist es auch sehr einfach, diese anzupassen oder zu erweitern. Gerade in der Softwareentwicklung geht es früher oder später nicht mehr ohne die Automatisierungen, da neue Features und Updates immer schneller auf den Markt kommen. Die Methode stellt daher einen klaren Wettbewerbsvorteil dar, wenn die Technische Dokumentation fast zeitgleich mit dem Produkt fertig ist. Wenn man sich unsicher ist, ob Docs-as-Code eine mögliche Variante zur bisherigen Dokumentationserstellung ist, dann ist es von Vorteil, einen PoC (Proof of Concept) auszuführen und klein anzufangen. Das kann zum Beispiel ein Quick Start Guide oder das erste Kapitel eines Handbuchs sein. Im Großen und Ganzen sind Docs-as-Code keine Raketenwissenschaft, sondern ein praktisches Werkzeug, das allen Beteiligten Zeit und Arbeit spart. Versuchen Sie es doch auch einmal. 

¹ Textbasiertes Eingabeformat zur Erstellung von Dokumentation. https://www.hznet.de/textproc/asciidoc-intro.html

² https://asciidoctor.org/ und https://antora.org/ (open source)

³ Auszeichnungssprache mittels derer Maschinen Textinhalte gliedern und formatieren können – https://www.eology.de/wiki/markup

⁴ Vereinfachte Auszeichnungssprache, die bereits vor der Konvertierung in die Zieldatei (wie etwa HTML) leicht lesbar ist – https://de.wikipedia.org/wiki/Markdown

⁵ Wandelt zum Beispiel Markdown-Dateien in HTML um https://cmsstash.de/empfehlungen/static-site-generatoren

⁶ Softwaretools, mit deren Hilfe Änderungen am Quellcode im Zeit­verlauf verwaltet werden können wie Git, GitHub, GitLab, SVN, Bitbucket

https://git-scm.com/

⁸ CI = Continous Integration, CD = Continous Deployment – über so genannte Pipelines wird der Entwicklungsprozess automatisiert vom Testen bis hin zum Deployment.

⁹ Erstellprozess einer bestimmten Version einer Software bzw. Dokumentation

¹⁰ Automatisierte Installation und Konfiguration von Software auf der dafür vorgesehenen Plattform/Server/Cloud

¹¹ Integrierte Entwicklungsumgebung (Quellcode-Editor), wie Eclipse, Visual Studio oder Atom

¹² https://www.sphinx-doc.org/en/master/

¹³ https://redoc.ly/ 

¹⁴ Integrierte Entwicklungsumgebung (Quellcode-Editor), wie Eclipse, Visual Studio, Atom

¹⁵ Master branch = Haupt- bzw. Endversion, die jederzeit veröffentlicht werden kann.

¹⁶ Feature branch = Arbeitsversion der Dokumentation oder des Codes, in der Änderungen vorgenommen und geprüft werden, bevor sie in die Endversion eingepflegt werden.

¹⁷ Erstellprozess einer bestimmten Version einer Software bzw. Dokumentation

Links zum Weiterlesen

https://docs-as-co.de/

https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html#what-Docs-as-Code-tools-means

https://www.informatik-aktuell.de/entwicklung/ methoden/Docs-as-Code-die-grundlagen.html

https://document360.com/blog/docs-like-code-is-it-worth-the-hassle

https://redoc.ly/

https://www.heise.de/hintergrund/Documentation-as-Code-mit-Asciidoctor-4642013.html

Texteditoren

https://atom.io/, https://www.sublimetext.com

Statische Seitengeneratoren

https://www.sphinx-doc.org/en/master/, https://jekyllrb.com/, https://gohugo.io/

Versionskontrollsysteme

https://git-scm.com/, https://github.com/, https://about.gitlab.com/

Dokumentation nach dem Docs-as-Code-Prinzip erstellen.