Docs – „as Code“ oder „as CCMS“?

Docs-as-Code ist in den letzten Jahren vor allem in der Software-Dokumentation immer beliebter geworden. In weiten Teilen der Technischen Kommunikation ist das Konzept aber immer noch unbekannt. Verbirgt sich hier also das nächste große Ding für Technische Redaktionen? Oder sind Component Contentmanagement-Systeme (CCMS), die viele Technische Redaktionen einsetzen, die bessere Alternative? Die Antwort ist – wie in so vielen Dingen: „Kommt darauf an!“

Was ist Docs-as-Code?

Docs-as-Code ist ein Sammelbegriff für mehrere Auszeichnungssprachen, die vor allem in der Software-Dokumentation eingesetzt werden. Bekannte Beispiele für Docs-as-Code sind etwa Markdown oder AsciiDoc. Es gibt auch andere Auszeichnungssprachen, die nicht dazugerechnet werden, die prominentesten darunter sind vermutlich HTML und XML.

Gemeinsam ist Docs-as-Code ebenso wie z. B. XML, dass sie ausschließlich mit ASCII-Zeichen dargestellt wird. Das Konzept der XML-artigen Auszeichnungssprachen liegt darin, Informationen hierarchisch und semantisch zu ordnen. Sie verlieren dadurch stark an Lesbarkeit (und Schreibbarkeit) gegenüber reinem, unstrukturiertem Text.

Docs-as-Code ist demgegenüber ein Kompromiss. Die Auszeichnungen integrieren sich besser in den Textfluss und sind dadurch leichter von Menschen lesbar. Dafür sind semantische Kategorisierungen schlechter möglich und auch Texthierarchien lassen sich nur begrenzt darstellen. Es ist also eher als Layoutanweisung zu verstehen, denn als semantische Strukturierung.

Warnhinweis als AsciiDoc-und XML-Struktur

Welche Vorteile hat Docs-as-Code?

Docs-as-Code hat deutliche Vorteile, wenn es darum geht, sich als Technische Redaktion in Software-Entwicklungsumgebungen einzubringen. Mit Markdown oder AsciiDoc lässt sich die Zusammenarbeit mit Entwicklern deutlich vereinfachen und die Dokumentation kann direkt in die Versionierung der Software-Releases einbezogen werden.

Ein weiterer Vorteil ist die Plattform-Unabhängigkeit des Konzepts. Dies gilt sowohl für die Dokumente als auch für die Software-Umgebungen. Denn die einzelnen Elemente einer Docs-as-Code-Umgebung (Editor, Browser, Repositories und Konverter) lassen sich aus einer großen Zahl an eigenständigen Softwarepaketen zusammenstellen, die auf diversen Betriebssystemen lauffähig sind. Oft sind dies Open-Source-Pakete, sodass die Initialkosten vergleichsweise moderat sind.

Allerdings kann der Abgleich der Softwarepakete bei Versionssprüngen zum Problem werden, wenn die Version des einen Softwarepakets nicht mehr reibungslos mit der neuen Version des anderen Pakets zusammenarbeitet.

Oft ist auch die Anpassung der Publikationsstraße auf gängige Anforderungen in der modernen Technischen Kommunikation schwierig: Content-Wiederverwendung, Übersetzungsmanagement und die Ausgabe der Dokumentation in verschiedenen Medienvarianten gibt es bei Docs-as-Code nicht out-of-the-box.

Was Redaktionen tun sollten

Technische Redaktionen sollten deshalb bei der Entscheidung für oder gegen Docs-as-Code ähnlich vorgehen wie bei jeder Systementscheidung. Eine schnell hingebaute Systemlösung mag im ersten Moment verführerisch erscheinen. Es kann aber durchaus sein, dass die vermeintlich billige Lösung langfristig teurer kommt. Faktoren dabei sind der Wartungsaufwand für die Softwarekomponenten, die etwas sperrige Schreibmethodik und der hohe Anpassungsaufwand für Anforderungen wie Terminologiemanagement, Medienvarianten oder Lokalisierung.

In manchen Fällen wird dieser zusätzliche Aufwand aufgewogen durch die engere Zusammenarbeit mit dem Entwicklungsteam. Wer allerdings bereits mit einem XML-basierten CCMS arbeitet, muss sich bewusst machen, dass durch die Entscheidung für Docs-as-Code die Datenqualität des Contents sinkt. Denn, wie oben bereits gezeigt, gehen beim Wechsel von XML auf Docs-as-Code semantische und strukturelle Informationen verloren. Es ist deshalb oft die bessere Variante, Docs-as-Code als Ausgabeformat des Contentmanagement-Systems zu erstellen und die Inhalte weiterhin XML-basiert zu pflegen.

Welche Erfahrungen haben Sie mit Docs-as-Code gemacht? Wir freuen uns auf die Diskussion.