Artikel

Docs-as-Code: Automatisierte Software Dokumentation

Die Welt der Softwareentwicklung verändert sich ständig, und mit ihr auch die Art und Weise, wie wir Software dokumentieren. Eine innovative Methode, die in den letzten Jahren an Popularität gewonnen hat, ist “Docs-as-Code” oder Dokumentation als Code. In diesem Artikel werden wir uns mit dieser spannenden Entwicklung auseinandersetzen und den Anwendungsbereich in der Technischen Dokumentation genauer beleuchten.

In unserem Meetup zur Zukunft der Technischen Kommunikation haben wir uns ebenfalls dem Thema gewidmet und praktische Anwendungen getestet und diskutiert.

Was ist Docs-as-Code?

Docs-as-Code ist ein Ansatz zur Erstellung und Verwaltung von Software-Dokumentation, bei dem die Dokumentation wie Quellcode behandelt wird. Statt traditioneller Dokumentationswerkzeuge kommen dabei Code-basierte Tools und Versionierungssysteme zum Einsatz. Dies ermöglicht eine agile und kollaborative Erstellung, Aktualisierung und Verwaltung von Dokumentationen – Entwickler und technische Redakteure können gemeinsam an der Dokumentation arbeiten. Dies fördert die Zusammenarbeit und Integration der Dokumentation in den gesamten Entwicklungszyklus.

Anwendung findet der Ansatz vor allem in der Softwaredokumentation, bietet aber auch für Technische Dokumentation einige Vorteile.

Typische Auszeichnungssprachen

Anstatt die technische Dokumentation mit einem klassischen Autorensystem zu erfassen, kann ebenfalls eine leichtgewichtige Auszeichnungssprache verwendet werden, die die Struktur und das Format der Dokumentation definieren. Einige der typischen Auszeichnungssprachen kurz erklärt:

Markdown ist eine leicht verständliche und weit verbreitete Markup-Sprache. Sie ermöglicht die einfache Formatierung von Text und unterstützt das Hinzufügen von Links, Bildern und Listen. Die Syntax ist minimal und intuitiv, was Markdown zu einer beliebten Wahl für viele Entwickler macht.

AsciiDoc ist eine mächtigere Markup-Sprache mit erweiterten Funktionen im Vergleich zu Markdown. Sie ermöglicht komplexe Strukturen, Tabellen und die Verwendung von Makros. AsciiDoc ist besonders geeignet für umfangreiche Dokumentationen mit anspruchsvollen Anforderungen.

reStructuredText ist eine Markup-Sprache, die speziell für die Python-Dokumentation entwickelt wurde. Sie ist einfach zu lesen und zu schreiben und ermöglicht die Integration von Code-Beispielen. Diese Sprache wird oft in Kombination mit dem Werkzeug Sphinx für die Erstellung von Dokumentationsprojekten verwendet.

YAML wird häufig für die Konfiguration von Docs-as-Code-Workflows verwendet. YAML ist eine Datenformatsprache, die einfach zu schreiben und zu lesen ist. YAML wird verwendet, um Metadaten, Konfigurationen und Strukturen in der Dokumentation zu definieren.

Notwendige Komponenten

Die Wahl einer geeigneten Auszeichnungssprache ist entscheidend. Diese Sprachen ermöglichen die strukturierte Auszeichnung von Texten, um eine klare Darstellung und Konsistenz in der Dokumentation zu gewährleisten. Um die kollaborative Arbeit zwischen Entwicklern und Redakteuren zu gewährleisten und einen automatisierten Dokumentationsprozess zu generieren, sind verschiedene Tools notwendig.

Die wesentlichen Komponenten sind:

  • Versionskontrolle: Ein Versionskontrollsystem wie Git ist entscheidend, um Änderungen an der Dokumentation nachzuverfolgen, Zusammenarbeit zu erleichtern und verschiedene Versionen zu verwalten.

  • Texteditor oder IDE: Ein Texteditor oder eine integrierte Entwicklungsumgebung (IDE) ermöglicht das Schreiben von Docs-as-Code. Einige Editoren bieten Funktionen wie Vorschau und Syntaxhervorhebung, um die Arbeit zu erleichtern.

  • Build-Tools: Tools wie Jekyll, Hugo oder Sphinx helfen beim Erstellen der Dokumentationswebsite aus dem Quellcode. Diese Build-Tools ermöglichen die Konvertierung von Markup-Dateien in verschiedene Ausgabeformate, wie HTML oder PDF.

  • Dokumentationsgenerator: Ein Dokumentationsgenerator, wie beispielsweise MkDocs oder Docusaurus, bietet eine Struktur für die Organisation von Dokumentationsinhalten und erleichtert die Erstellung einer benutzerfreundlichen Website.

  • Continuous Integration (CI): Die Integration von Docs-as-Code in den CI/CD-Prozess ermöglicht automatisierte Builds und Tests der Dokumentation bei jeder Änderung im Quellcode. Dies gewährleistet eine zuverlässige und konsistente Bereitstellung.

  • Kollaborationsplattform: Eine Plattform zur Zusammenarbeit, wie GitHub oder GitLab, ermöglicht es Teams, gemeinsam an der Dokumentation zu arbeiten, Rückmeldungen zu geben und Änderungen vorzunehmen.

Durch die Implementierung dieser Elemente kann Docs-as-Code effektiv in den Technischen Kommunikationsprozess integriert werden, um agile, kollaborative und gut verwaltete Dokumentationen zu erstellen.

Das klingt aber nach einer Menge Aufwand, oder?

Die Umstellung auf Docs-as-Code erfordert anfangs einen höheren Arbeitsaufwand – für die Anpassung bestehender Dokumentationen und den Lernprozess. Teammitglieder müssen neu geschult werden, es entstehen möglicherweise Kosten für neue Werkzeuge und Programme. Für umfangreiche Projekte können komplexe Workflows und Pipelines erforderlich sein. Docs-as-Code kann auch einfach überdimensioniert sein, wenn die zu dokumentierenden Informationen eher einfacher Natur sind. Es ist also auch wichtig potenzielle Nachteile zu berücksichtigen. Langfristig kann durch die Integration von Dokumentation in den Entwicklungsprozess aber Effizienz und Zusammenarbeit gesteigert werden.

Vorteile für die Technische Kommunikation

Docs-as-Code ist zweifellos eine spannende Entwicklung. Die Auswahl der richtigen Werkzeuge und die sorgfältige Gestaltung von Workflows sind entscheidend für den Erfolg dieser Methode. Trotz einiger Herausforderungen bietet Docs-as-Code einen vielversprechenden Ansatz für die Technische Kommunikation. Hier sind noch einmal alle Vorteile im Überblick:

  • Agile Dokumentation: Docs-as-Code passt sich nahtlos an die dynamischen Anforderungen von agilen Umgebungen an. Die Technische Redaktion kann in Echtzeit auf Entwicklungsänderungen reagieren, da die Dokumentation als integraler Bestandteil des Entwicklungsprozesses betrachtet wird.

  • Kollaborative Erstellung: Docs-as-Code fördert die Zusammenarbeit zwischen Entwicklern und Technischen Redakteuren. Die gemeinsame Verwendung von Markup-Sprachen und Entwicklungswerkzeugen schafft eine Brücke zwischen den beiden Disziplinen. Diese Zusammenarbeit führt zu klaren und präzisen Dokumentationen, die besser auf die Bedürfnisse der Endnutzer abgestimmt sind.

  • Automatisierte Workflows: Die Automatisierung von Workflows und Prozessen ist ein entscheidender Vorteil von Docs-as-Code. Durch die Integration von CI/CD-Pipelines können Rechtschreibprüfungen, Formatüberprüfungen und andere Qualitätsprüfungen automatisch durchgeführt werden, bevor die Dokumentation veröffentlicht wird.

  • Versionierung: Durch die Integration von Docs-as-Code in Versionskontrollsysteme wird eine umfassende Versionierung und Rückverfolgbarkeit ermöglicht. Dies ist besonders wichtig für die Technische Redaktion, da Änderungen in der Dokumentation nachvollzogen werden können, und es gibt klare Mechanismen für die Zusammenarbeit bei der Erstellung von Inhalten.

  • Skalierbarkeit und Wiederverwendbarkeit: Docs-as-Code ermöglicht eine effektive Skalierbarkeit und Wiederverwendbarkeit von Inhalten. Durch die Verwendung von Markup-Sprachen können bestimmte Dokumentationselemente leicht wiederverwendet und in verschiedenen Teilen des Projekts implementiert werden. Dies führt zu einer konsistenten und effizienten Nutzung von Ressourcen.

  • Multi-Channel-Ausgabe: Technische Redaktionen stehen oft vor der Herausforderung, Inhalte für verschiedene Kanäle und Plattformen bereitzustellen. Docs-as-Code ermöglicht eine einfache Anpassung der Dokumentation für verschiedene Ausgabeformate, sei es für Online-Plattformen, gedruckte Handbücher oder andere Formate.

Insgesamt bietet Docs-as-Code in der Technischen Redaktion eine moderne und effektive Methode, um den sich ständig wandelnden Anforderungen und Dynamiken der Softwareentwicklung gerecht zu werden. Durch die Integration von Dokumentation in den Code-Entwicklungsprozess können Technische Redaktionen hochwertige, aktuelle und kollaborative Dokumentationen erstellen, die einen Mehrwert für Entwickler und Endnutzer gleichermaßen bieten.

Abonnieren Sie den kostenfreien Newsletter von PANTOPIX.
Wir informieren Sie gerne regelmäßig über neue Artikel.

Artikel

Topic-Orientierung in der Technischen Kommunikation

Die Umstellung von einer Dokumenten-basierten auf eine Topic-orientierte Herangehensweise in der Technischen Kommunikation bringt tiefgreifende Veränderungen mit sich, die zahlreiche Vorteile bieten.
Doch was genau verbirgt sich hinter diesem Begriff der Topic-Orientierung, und warum ist er für die technische Kommunikation so sinnvoll?

weiterlesen >
Artikel

PIM-Systeme auf Basis von Wissensgraphen

Industrien verlassen sich auf Product Information Management (PIM)-Systeme, um Produktinformationen zu erstellen, zu verwalten und über verschiedene Kanäle zu verteilen. 

Die Herausforderungen, die dabei auftreten, können wir mit der Entwicklung von PIM-Systemen auf der Basis von Wissensgraphen entgegnen. 

weiterlesen >
Artikel

Knowledge Graph Embeddings

Unterschiedliche Datenquellen in einer Wissensdatenbank zusammenzuführen und die semantische Repräsentation der dort enthaltenen Informationen können die Technische Kommunikation erheblich erleichtern. Der Aufbau einer Wissensdatenbank mithilfe semantischer Wissensgraphen bietet zahlreiche Vorteile, darunter die wichtige Möglichkeit, den Wissensgraphen kontinuierlich zu erweitern. Eine Methode zur Erweiterung des Wissens besteht in der Anwendung von Einbettungen für Wissensgraphen (Knowledge Graph Embeddings).

weiterlesen >

Ihr Ansprechpartner

Prof. Dr. Martin Ley
Partner und Senior Consultant