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?
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.
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).
Potenziale von KI in der Technischen Kommunikation
In jüngster Zeit hat KI viel
Aufmerksamkeit erregt, da sie die Möglichkeiten eröffnet manuelle Aufgaben zu automatisieren. Die Innovationskraft dieses Technologiefortschritts wirft jedoch auch die Frage auf, ob wir in der technischen Kommunikation bewährte Ansätze und Methoden – von Metadaten über semantische Informationsmodelle bis hin zu Wissensgraphen – über Bord werfen müssen.
Bedeutung von Semantik in der Technischen Kommunikation
Heute wird immer häufiger über Semantik gesprochen, insbesondere im Zusammenhang mit Begriffen wie “Semantisches Web” oder “Semantisches Wissensmanagement”. Doch was genau bedeutet Semantik und wie relevant ist sie für die Technische Dokumentation?
Ihr Ansprechpartner
Prof. Dr. Martin Ley
Partner und Senior Consultant
- martin.ley@pantopix.com
