parson AGDokumentation automatisieren mit Docs-as-code
Für benutzerfreundliche Entwicklerdokumentation
Technische Dokumentation wird in der Regel modular erstellt, um sie gemeinsam zu bearbeiten, zu versionieren und in Varianten bereitzustellen. In der Software-Branche haben Entwickler:innen ähnliche Anforderungen, wenn es darum geht, den Quellcode zu verwalten. Viele Entwickler:innen schreiben auch selbst Dokumentation. Diese sollte möglichst eng mit dem Code verknüpft sein, damit sie gemeinsam mit der Software aktualisiert und beim Release veröffentlicht werden kann.
Der Docs-as-Code-Ansatz meistert diese Herausforderungen. Docs-as-code behandelt die Dokumentation genauso wie den Quellcode der Software: Die Dokumentation wird im Versionsverwaltungssystem gespeichert, in Entwicklungsumgebungen bearbeitet und über Continuous-Integration-Pipelines veröffentlicht. So können mehrere Autor:innen gleichzeitig an der Dokumentation arbeiten. Automatisierte Workflows stellen sicher, dass die Dokumentation schnell verfügbar ist, sie ist nah am Code, einheitlich und immer aktuell.
Wir implementieren Docs-as-code
Wir richten für Ihre Softwaredokumentation eine Docs-as-Code-Umgebung ein. Dafür wählen wir passende Tools aus, erarbeiten eine Informationsarchitektur und integrieren die Dokumentation in die bestehende Entwicklungsumgebung.
Zusätzlich erstellt parson für Sie Softwaredokumentation, Entwicklerdokumentation oder API-Dokumentation mit dem Docs-as-code-Ansatz. So arbeiten wir.
Ihre Ansprechpartner:innen
Docs-as-code
Unsere Kundschaft
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 Dokumentation für Software. Docs-as-code bedeutet, dass Sie die Dokumentation auf die gleiche Weise behandeln wie den Quellcode. 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).