Können Softwareentwicklung und Technische Redaktion gemeinsam dokumentieren? So unterstützt parson Siemens beim Aufbau eines kollaborativen Redaktionssprozesses

Der Siemens-Bereich „Digital Industries, Factory Automation, Information Management” will seine Technische Dokumentation zukunftsfähig aufstellen und hat dafür einen Redaktionsprozess für die gemeinsame Dokumentation durch Softwareentwicklung und Technische Redaktion entworfen. parson hat den Entwurf evaluiert.

Die Ausgangssituation: Getrennte Dokumentation, kein einheitlicher Redaktionsprozess

Softwareentwickler:innen und Technische Redakteur:innen verfassen die Nutzungsinformation (Dokumentation) getrennt voneinander. Die Softwareentwicklung speichert und verwaltet die Nutzungsinformation in Git-Repositories. Die Technische Redaktion erstellt Nutzungsinformation in einem Redaktionssystem (CCMS), dessen Inhalte nach DITA-XML konvertiert, mit der Dokumentation der Softwareentwicklung zusammengeführt und mit Metadaten angereichert werden. Die Technische Redaktion kümmert sich auch um die Übersetzungsprozesse, Qualitätskontrolle und Freigabeprozesse.

Das Ziel: Gemeinsame Dokumentation und einheitlicher Redaktionsprozess

Siemens möchte die Nutzungsinformation der Softwareentwicklung und der Technischen Redaktion in einem einheitlichen Redaktionsprozess zusammenführen. So sollen der Aufwand für die Erstellung verringert sowie die Qualität und Auslieferung verbessert werden.

Auf dem Weg zur Lösung: Entwurf für einheitlichen Redaktionsprozess

Siemens hat einen gemeinsamen Redaktionsprozess für beide Rollen entworfen, der folgende Schritte umfasst:

• Die Softwareentwickler:innen erstellen Dokumentation mit Hilfe der Docs-as-Code-Methode. Dabei bleiben sie in ihrer gewohnten Entwicklungsumgebung.
• Git-Repositories dienen als zentrales Integrationssystem unter Verwendung von DITA-XML.
• Es wird ein einheitliches Metadatenvokabular für die gesamte Nutzungsinformation verwendet.
• Es gibt einen einheitlichen Freigabe-, Übersetzungs- und Publikationsprozess.
• Die Technische Redaktion koordiniert den Dokumentationsprozess, um die Qualität sicherzustellen.
• Die Nutzungsinformation wird über das Content-Delivery-Portal Fluid Topics veröffentlicht.

parson evaluiert Prozessentwurf

Die Expert:innen von parson haben den Prozessentwurf analysiert und bewertet. Dabei haben sie folgende Aspekte genauer unter die Lupe genommen:

• Integration: Git-Repositories als zentrales Integrationssystem unter Verwendung von DITA-XML als Integrationsformat und Oxygen als Integrations-Tool
• Arbeitsumgebung: Unterschiedliche Tools und Dateiformate, mit denen Entwickler:innen und Technische Redaktion arbeiten: Visual Studio Code, Component Content Management System (CCMS), Oxygen XML Author, Markdown und DITA-XML
• Redaktionelle Prozesse: Review, Freigabe und Übersetzung
• Qualitätssicherung: Konsistenz der Repositories, Vorlagen und Validierung für Markdown und DITA-XML
• Content Delivery: Metadatenverwaltung zur Veröffentlichung mit dem Content-Delivery-Portal Fluid Topics

Konzeptpapier und User Stories

Die Ergebnisse der Analyse mit einer Bewertung der Risiken und Vorschlägen für entsprechende Gegenmaßnahmen hat parson in einem ausführlichen Konzeptpapier festgehalten. Darüber hinaus formulierte parson die Anforderungen von Siemens an die geplante Lösung in Form von User Stories.

Mit diesen beiden Dokumenten verfügt Siemens nun über eine solide Grundlage für die Implementierung eines einheitlichen Prozesses.

Nächste Schritte

• Harmonisierung der Formate, Prozesse, Tools
• Strategie für Übersetzung festlegen
• KI in die täglichen Prozesse integrieren und Use Cases sammeln
• ein komplettes Release mit neuen Prozessen durchleben

Über Siemens, "Digital Industries, Factory Automation and Information Management"

Für uns stehen unsere Kunden im Mittelpunkt. Mehrwert für sie zu schaffen ist, was uns antreibt! Durch die Verbindung der realen Welt der Automatisierung mit der digitalen Welt der Informationstechnologie (IT) ergeben sich für unsere Kunden in allen Branchen völlig neue Möglichkeiten. Denn so können sie sichere Entscheidungen treffen und ihre digitale Transformation beschleunigen, um ein Digital Enterprise zu werden. Mit unserem einzigartigen Portfolio leisten wir einen entscheidenden Beitrag zu nachhaltigen industriellen Innovationen – die den Alltag verändern und helfen, eine bessere Welt von Morgen zu gestalten, für Gesellschaften und Menschen weltweit. 

https://www.siemens.com/de/de/unternehmen/konzern/unternehmensstruktur/…