Docs-as-code für die Technische Dokumentation

Docs-as-code für Anwender- und Entwicklerdokumentation. So arbeiten wir

• Anforderungen analysieren. Gemeinsam mit Ihnen analysieren wir die Anforderungen Ihrer Zielgruppen und setzen eine geeignete Docs-as-code-Umgebung aus. Dabei können verschiedene Werkzeuge und Formate zum Einsatz kommen, z. B. AsciiDoc, Markdown oder auch DITA-XML.
• Pipelines entwickeln. Wir entwickeln Pipelines für die automatische Erzeugung der Ausgabeformate wie HTML oder PDF und integrieren die Publikations-Skripte bei Bedarf in Ihre Build-Umgebung, sodass die Publikation weitgehend automatisiert werden kann.
• Workflows definieren. Gemeinsam mit Ihnen definieren wir die Workflows für die Dokumentation als Teil der Entwicklungsprozesse, z. B. wie Dokumenationsaufgaben in einem Issue-Tracker wie JIRA verwaltet werden.
• Ablagestrukturen bestimmen. Wir definieren die Ablagestrukturen und Branching-Strategie für die Dokumentation innerhalb Ihres Versionskontrollsystems, z. B. Git.
• Informationsarchitektur entwickeln. Wir erarbeiten eine Informationsarchitektur für die Dokumentation und entwickeln Vorlagen und Terminologielisten für Ihre Autor:innen, egal ob Technische Redaktion oder Softwarentwicklung.
• Qualitätsicherung integrieren. Auf Wunsch integrieren wir Skripte und Schreibregeln für die automatisierte Prüfung von erstellten Inhalten, z. B. auf Basis einer Linters wie Vale, der natürliche Sprache anhand von Mustern analysiert.
• Tools auswählen und einrichten. Wir unterstützen Sie bei der Auswahl und Einrichtung von Tools für die Erstellung und Veröffentlichung von Inhalten, z. B. in einem Entwicklerportal. Dazu gehören u. a. Editoren wie Visual Studio, IntelliJ oder Oxygen XML Author sowie Static Site Generators wie Antora oder Jekyll.

Weitere Informationen rund um das Thema Docs-as-code finden Sie auch in unseren FAQs.

FAQs – Häufig gestellte Fragen zum Thema Docs-as-code

Was ist Docs-as-code?

Docs-as-code ist ein Ansatz zur Erstellung und Bereitstellung von Technischer Dokumentation. Docs-as-code bedeutet, dass Sie die Dokumentation auf die gleiche Weise behandeln wie den Quellcode einer Software. Der Docs-as-code-Ansatz kombiniert zwei wichtige Aspekte:

• Sie verwenden für die Dokumentationsdateien die gleichen Werkzeuge wie die Entwickler:innen, z. B. IDEs (integrated development environments), Versionskontrollsysteme und Werkzeuge für Continuous Integration und Delivery.
• Sie verwenden die gleichen Methoden wie die Entwickler, z. B. agiles Projektmanagement und Scrum.

Was sind die Vorteile von Docs-as-code?

Der Docs-as-code bietet viele Vorteile, hier sind einige:

• Kosten sparen. Indem sie die gleichen Tools und Prozesse für die Entwicklung und die Dokumentation verwenden, können Softwareunternehmen Kosten einsparen. So muss z. B. nicht in jedem Fall ein Redaktionssystem für die Softwaredokumentation beschafft werden.
• Versionierung und Zusammenarbeit. Mit Versionskontrollsystemen wie Git arbeiten mehrere Autor:innen gleichzeitig an der Dokumentation und können so Änderungen nachvollziehen und ggf. korrigieren.
• Workflows. Automatisierte Workflows sorgen dafür, die Dokumentation automatisiert zu erstellen, zu testen und zu veröffentlichen.
• Integration der Autor:innen. Folgen die Autor:innen demselben Arbeitsablauf wie die Entwicklung, sind sie vollständig in den Produktentwicklungsprozess integriert.
• Entwickler:innen schreiben. Die Entwicklung kann direkt an der Dokumentation mitarbeiten, da die Mitarbeitenden nicht die Umgebung wechseln müssen.

Welche Tools gibt es für Docs-as-code?

• Sie benötigen einen Texteditor, z. B. Visual Studio Code oder IntelliJ. Entwicklerdokumentation wird oft in einer leichtgewichtigen Markup-Sprache wie Markdown oder AsciiDoc geschrieben. Aber auch das XML-Format DITA kann in einer Docs-as-code-Umgebung eingesetzt werden.
• Für die Versionskontrolle können Sie zum Beispiel Git verwenden.
• Als Continuous-Integration-Tool eignen sich Jenkins, Bamboo oder das integrierte GitLab CI, um Inhalte zu veröffentlichen, die im Repository des Versionskontrollsystems gespeichert sind.
• Für den Output nach HTML benötigen Sie einen statischen Site-Generator. Die meisten Generatoren für statische Websites erstellen jedoch nur sehr einfache HTML-Seiten. Für Technische Dokumentationen benötigen Sie erweiterte Funktionen wie Versionierung oder Suchintegration. Nur wenige Website-Generatoren bieten diese erweiterten Funktionen, z. B. Antora (AsciiDoc) und Sphinx (reStructuredText).

Was ist der Unterschied zwischen DITA und Docs-as-code?

DITA und Docs-as-code sind zwei unterschiedliche, aber kombinierbare Konzepte in der Technischen Dokumentation. 

DITA ist ein offener XML-Standard zur modularen, wiederverwendbaren und strukturierten Erstellung technischer Inhalte. Das Ziel: eine einheitliche, strukturierte Dokumentation, die leicht wiederverwendbar ist und automatisiert veröffentlicht werden kann. Lesen Sie mehr über DITA-XML für die Technische Dokumentation

Docs-as-code ist ein Ansatz, bei dem Technische Dokumentation wie Quellcode behandelt wird. Das Ziel: die nahtlose Integration von Dokumentation in den Softwareentwicklungsprozess – schnell, kollaborativ und transparent.

Tipp: Sie können DITA-XML im Docs-as-code-Ansatz nutzen – z. B. DITA-Dateien in Git, mit automatischer Publikation via CI/CD (Continuous Integration/Continuous Delivery).

Muss ich programmieren können, um Docs-as-code zu nutzen?

Nicht unbedingt. Grundkenntnisse in Git und den verwendeten Formaten (z. B. Markdown oder AsciiDoc) reichen oft aus, um Docs-as-code anzuwenden. Viele Aufgaben können ohne Programmierung erledigt werden. Für die Integration in Continuous-Integration-Umgebungen sind jedoch oft tiefere technische Kenntnisse oder Programmierung notwendig. Komplexere Umgebungen werden daher oft von DevOps oder Technischen Redakteur:innen mit technischem Fokus betreut.

Wer schreibt die Dokumentation beim Docs-as-code-Ansatz?

Das hängt vom Team ab. Oft schreiben Entwickler:innen eine erste Fassung, Redakteur:innen überarbeiten sie sprachlich und strukturell. Docs-as-code erleichtert diese Zusammenarbeit.

Wie sieht der typische Workflow beim Docs-as-code-Ansatz aus?

1. Dokumentation wird lokal geschrieben (z. B. in Markdown).
2. Änderungen werden über Git hochgeladen.
3. Ein Review erfolgt über einen Pull Request.
4. Nach Freigabe wird die Doku automatisch veröffentlicht.

Ist Docs-as-code auch für kleinere Teams geeignet?

Ja! Gerade kleinere oder agile Teams profitieren, weil sie schneller Inhalte erstellen und veröffentlichen können – ohne großes Redaktionssystem.