Softwaredokumentation: Wenn Git und CMS aufeinandertreffen

Softwaredokumentation hat eigene Anforderungen, weil sich Software ständig verändert und Entwickler und Redakteure mit unterschiedlichen Werkzeugen und Formaten arbeiten. Ein modernes Redaktionssystem muss diesen Bruch zwischen Git und CMS technisch auflösen.

Kaum ist ein Softwarehandbuch fertig, ist die Software schon wieder einen Schritt weiter. Wer in der technischen Redaktion für Software arbeitet, kennt dieses Gefühl nur zu gut. Softwaredokumentation umfasst alle Inhalte, die Anwender und Administratoren beim Verstehen oder Bedienen einer Software unterstützen, von Handbüchern über Online-Hilfen bis zu API-Referenzen. Genau in diesem breiten Feld steckt oft ein sehr konkretes Problem: Entwickler und Redakteure arbeiten faktisch in zwei getrennten Welten, mit unterschiedlichen Werkzeugen und unterschiedlichen Formaten. Sobald diese beiden Welten nicht mehr synchron laufen, veraltet die Dokumentation schneller, als sie gepflegt werden kann. Das kann spürbare Folgen für Support-Anfragen und für das Vertrauen der Nutzer in die Anleitung haben.

Genau dieser Konflikt zieht sich durch den gesamten Beitrag. Wir schauen uns im Detail an, woran er liegt, welche organisatorischen Folgen er im Redaktionsalltag hat und was ein Redaktionssystem können muss, damit er gar nicht erst zum Dauerproblem wird.

Softwaredokumentation unterscheidet sich in fünf Punkten von klassischer technischer Dokumentation: ständige Veränderung, Format- und Werkzeugbruch, externe Entwickler als Zielgruppe, Systemumgebungen als Variantendimension und kontextsensitive Hilfe im Produkt.

Ständige Veränderung

Neue Versionen und Hotfixes lösen einander in kurzen Abständen ab, oft laufen mehrere Entwicklungslinien parallel. Dadurch lässt sich kaum eindeutig sagen, welche Anleitung zu welcher Softwareversion gehört, wenn die Dokumentation nicht von Anfang an strukturell auf diese Dynamik ausgelegt ist.

Format- und Werkzeugbruch zwischen Entwicklung und Redaktion

Das ist der Kernkonflikt aus der Einleitung, und er verdient einen genaueren Blick. Entwickler dokumentieren am liebsten dort, wo sie ohnehin arbeiten: direkt im Git-Repository, in Markdown, mit Branching und Merging als selbstverständlichem Arbeitsmodus. Technische Redakteure dagegen brauchen die Möglichkeiten eines CMS:

• XML als strukturiertes Format,
• Wiederverwendung von Textbausteinen,
• Variantensteuerung,
• Qualitätssicherung und
• Übersetzung.

Beide Anforderungen sind berechtigt, aber sie ziehen in unterschiedliche technische Richtungen. Wenn der Stand im Git-Repository und der Stand im CMS nicht sauber synchron gehalten werden, entstehen zwei Wahrheiten statt einer verlässlichen Quelle, mit allen Folgen für Konsistenz und Vertrauen in die Dokumentation.

Externe Entwickler als eigene Zielgruppe

Sobald sich eine Software über eine API oder ein SDK anbinden lässt, entsteht eine Zielgruppe, die es bei physischen Produkten in dieser Form nicht gibt. Partnerunternehmen brauchen keine Bedienungsanleitung, sondern Referenzdokumentation zu Endpunkten, Parametern und Authentifizierung, oft direkt aus dem Code generiert.

Systemumgebungen als eigene Variantendimension

Ob eine Software unter Windows, Linux, in der Cloud oder On-Premises betrieben wird, verändert Installationsschritte, Konfigurationsoptionen und mitunter ganze Arbeitsabläufe. Das kommt zu klassischem Versions- und Variantenmanagement noch als zusätzliche Dimension hinzu.

Kontextsensitive, ins Produkt integrierte Hilfe

Eine Maschine kann keine Tooltips anzeigen, die sich automatisch an den aktuellen Bedienzustand anpassen. Software schon. Anwender erwarten heute, dass Hilfe genau dort erscheint, wo sie gerade arbeiten, etwa als Tooltip, In-App-Guide oder Chat-Widget. Dazu gehören auch Querverlinkungen zwischen einzelnen Topics, statt isolierter Einzelseiten. Das stellt Redaktionen vor die Herausforderung, Inhalte nicht nur verständlich, sondern auch maschinenlesbar und modular genug für die Einbindung ins Produkt selbst aufzubereiten.

Die technischen Besonderheiten aus dem vorigen Abschnitt bleiben nicht folgenlos. Sie schlagen direkt auf den Arbeitsalltag von Redaktionen durch, und zwar auf eine Weise, die sich von klassischer technischer Redaktion deutlich unterscheidet.

Zeitdruck durch Sprints

In der Softwareentwicklung sind kurze, fest getaktete Arbeitszyklen längst Standard, meist zwischen einer und vier Wochen, wobei der Scrum Guide einen Monat als Obergrenze vorgibt. Anforderungen werden in einem Sprint erfasst, umgesetzt und ausgeliefert, und die Dokumentation soll idealerweise im selben Rhythmus mitwachsen. Für Redakteure bedeutet das, dass sie nicht mehr am Ende eines langen Projekts in Ruhe ein komplettes Handbuch schreiben, sondern fortlaufend kleine, in sich abgeschlossene Informationseinheiten liefern müssen, oft parallel zu mehreren Sprints in mehreren Teams gleichzeitig.

Schwergängige Ausspielung an softwarespezifische Kanäle

Eine Maschinendokumentation muss selten mehr als PDF und vielleicht eine Webhilfe bedienen. Bei Software kommen API-Referenzen, In-App-Hilfe und zunehmend Chatbots als eigene Ausgabekanäle hinzu, jeder mit eigenen technischen Anforderungen an Format und Struktur. Viele Redaktionssysteme sind auf diese Vielfalt an Kanälen, wie sie für Software typisch ist, nicht ausgelegt und stoßen hier an ihre Grenzen.

Ein Redaktionssystem für Softwaredokumentation muss sechs Fähigkeiten mitbringen: Git-Integration mit Markdown-Konvertierung, Variantenmanagement, Versionierungslogik, Übersetzungsautomatisierung, Ausspielung an softwarespezifische Kanäle und einen Medienworkflow mit automatisch generierten Screenshots. Nur dann funktioniert Softwaredokumentation im Alltag tatsächlich und nicht nur auf dem Papier.

• Nahtlose Git-Integration mit Markdown-Konvertierung. Dieser Konflikt lässt sich technisch auflösen, ohne dass eine Seite ihre gewohnte Arbeitsweise aufgeben muss. Ein modernes Redaktionssystem übernimmt die Konvertierung zwischen Markdown und XML automatisch im Hintergrund und unterstützt dabei auch Branching und Merging. Weil Markdown selbst keine festen Strukturvorgaben kennt, entspricht eine Konvertierung nicht automatisch dem vorgegebenen XML-Schema. Ein gutes System lässt diesen Import trotzdem zu, statt ihn zu blockieren, und gibt der Redaktion die Kontrolle, den Inhalt anschließend sauber in die passende Struktur zu bringen. So bleibt jede Seite in ihrer gewohnten Umgebung, und trotzdem existiert nur eine verlässliche Quelle.
• Variantenmanagement für Systemumgebungen und Konfigurationen. Die zuvor genannte Variantendimension lässt sich über bedingte Inhalte steuern, ergänzt um kundenindividuelle Leistungspakete, ohne dass für jede Kombination ein eigenes Dokument gepflegt werden muss.
• Versionierungslogik, gekoppelt an Softwareversionen und Release-Zyklen. Inhalte sollten sich direkt einer Softwareversion zuordnen lassen, damit zu jedem Release automatisch klar ist, welcher Dokumentationsstand dazugehört, statt das manuell nachzuhalten.
• Übersetzungsautomatisierung mit Anbindung an die UI-String-Lokalisierung. Die Begriffe, die in der Softwareoberfläche verwendet werden, sollten sich direkt mit den Übersetzungen in der Dokumentation abgleichen lassen. Das verhindert, dass ein Button in der Software anders heißt als in der Anleitung, ein Problem, das bei physischen Produkten in dieser Form kaum auftritt.
• Ausspielung an softwarespezifische Kanäle. Diese Kanäle müssen sich aus einer einzigen Quelle heraus bedienen lassen, ergänzt um klassisches Web und PDF, statt für jeden Kanal eigene Inhalte separat zu pflegen.
• Medienworkflow mit automatisiert generierten Screenshots und UI-Zuständen. Displaytexte, Buttonbeschriftungen und Bildschirmansichten lassen sich direkt aus der laufenden Software extrahieren, statt sie manuell zu pflegen.

Wer ein bestehendes Redaktionssystem ablösen möchte, findet im Beitrag Praxisnaher Projektplan für die Ablösung von CMS und Redaktionssystemen Hinweise zum Vorgehen.

Ein Redaktionssystem, das Git und CMS technisch verbindet, löst den Werkzeugbruch, aber nicht alles.

• Terminologie-Konsistenz über mehrere Teams hinweg bleibt eine organisatorische Aufgabe. Wenn jedes Entwicklungsteam relativ eigenständig arbeitet, driften Begriffe und Formulierungen leichter auseinander, selbst wenn die technische Synchronisation zwischen Git und CMS sauber funktioniert. Das lässt sich mit Terminologiedatenbanken und teamübergreifenden Standards abfedern, aber kein System nimmt diese Abstimmung vollständig ab.
• Quelltextdokumentation bleibt Domäne spezialisierter Tools aus der Softwareentwicklung. Diese sind näher am Code und dafür gebaut, Funktionen, Klassen und Parameter direkt aus dem Quelltext zu erschließen. Ein Redaktionssystem sollte hier nicht versuchen, diese Tools zu ersetzen.
• Reine Schnittstellendokumentation liegt aus demselben Grund außerhalb dessen, was ein Redaktionssystem leisten sollte. Auch hier übernehmen spezialisierte Entwicklungstools die eigentliche technische Tiefe. Das Redaktionssystem ergänzt sie bestenfalls um Kontext und redaktionelle Einbettung.

Softwaredokumentation unterscheidet sich von klassischer technischer Dokumentation nicht nur graduell, sondern strukturell. Der Konflikt zwischen Entwicklungswelt und Redaktionswelt, zwischen Git und CMS, zwischen Markdown und XML, ist dabei mehr als eine Werkzeugfrage. Er ist der Kern dessen, was diese Disziplin besonders macht. Ein Redaktionssystem, das diesen Konflikt technisch auflöst, Varianten für Systemumgebungen sauber abbildet und die richtigen softwarespezifischen Kanäle bedient, schafft die Grundlage dafür, dass Dokumentation mit dem Tempo der Softwareentwicklung mithalten kann, statt ihr ständig hinterherzulaufen.