Auf dem Weg zu einer produktiven Dokumentation
In einem vorangegangenen Blog-Post schrieb Tiia Järvenpää über Softwareproduktisierung und wie sie so eingesetzt werden kann, dass kundenspezifische Module und Anpassungen möglich sind. Wenn man sich auf eine solche Produktlösung zubewegt, ist es an der Zeit, die Verwaltung der Dokumentation zu verbessern, um sie zu unterstützen.
Da wir nun ein modulares und anpassbares Produkt einführen, benötigen wir eine entsprechende Dokumentation. Das wichtigste Dokument ist eine Funktionsspezifikation, die die Funktionen beschreibt. In einem Produktsystem sind die grundlegenden Funktionen – und damit auch die Kapitel der Funktionsspezifikation, in denen diese beschrieben werden – in den meisten Kundenprojekten gleich. Einige Funktionen sind in optionalen Produktmodulen enthalten, und einige Funktionen sind spezifisch für ein einzelnes Projekt.
Von Word-Dateien zum Dokumentationssystem
Bei der Verwendung herkömmlicher linearer Dokumentationen wie Word-Dokumenten ist es zwar einfach, die gemeinsamen Merkmale in neue Projekte zu kopieren und einzufügen, Änderungen in einer großen Anzahl separater Dokumente sind jedoch sehr fehleranfällig. Aus diesem Grund begannen wir mit der Suche nach einem modularen Dokumentationssystem, das Wiederverwendung und gleichzeitig Anpassung ermöglicht.
Um die Produktisierung zu unterstützen und die Konsistenz und Qualität unserer Dokumentation zu verbessern, haben wir im Dokumentationssystem nach den folgenden Funktionen gesucht:
- Modularität: Jedes Kapitel ist eine separate Datei, ein „Thema“, das Sie in mehreren Dokumenten wiederverwenden können. Einmal schreiben, oft verwenden – und an einem einzigen Ort auf dem neuesten Stand halten.
- Strukturierter Inhalt: Der Inhalt wird in Elementen wie „Absatz“ und „Titel“ organisiert. Im endgültigen Dokument erscheint jedes Element entsprechend dem, was wir in einem Teleste-spezifisches Stylesheet. Dadurch bleiben Layout und Formatierung immer gleich.
- Versionierung: Es ist einfach, die Änderungen in Dokumenten zu verfolgen, da die Themen und Dokumente Versionierung und Versionsvergleiche unterstützen. Es ist möglich, viele Versionen zu verwalten und nicht nur auf frühere Versionen zurückzugreifen.
- Schlüsselwörter: Wir können Tags verwenden, um bestimmte Themen oder sogar einzelne Sätze herauszufiltern. Dadurch können wir unsere Dokumente für verschiedene Kunden und Projekte anpassen, aber dennoch für alle den gleichen Quellinhalt verwenden.
- Variablen: Wir können Variablen im Inhalt verwenden – beispielsweise wird die Variable „Projekt“ im endgültigen Dokument durch den Projektnamen ersetzt.
Vorbereitung auf das Schreiben in einem zentralisierten System
Das Erstellen von Dokumentationen in einer modularen und strukturierten Umgebung erfordert eine neue Denkweise und etwas Schulung. Deshalb haben wir ein eigenes Team für diesen Zweck. Wir haben die Dokumenttypen identifiziert, die vom neuen Ansatz profitieren, und begonnen, die ersten Dokumente im System zu erstellen und zu pflegen.
Um über ein Produkt schreiben zu können, müssen wir auch die Begriffe festlegen, die wir verwenden, um darüber zu sprechen. Daher haben wir im Rahmen der Produktentwicklungsarbeit auch ein Entwicklungsprojekt zur Harmonisierung der Terminologie in unserer Dokumentation gestartet. Wir haben eine Liste der Begriffe zusammengestellt, die wir häufig in unserer Dokumentation verwenden, darunter allgemeine Eisenbahnterminologie und auch Begriffe, die wir verwenden, um uns auf Teleste-spezifische Subsysteme und Produkte und entschied über die besten zu verwendenden Begriffe sowie Definitionen für jeden Begriff. Die Angabe der Bedeutung der Begriffe ist genauso wichtig wie die Begriffe selbst, um sicherzustellen, dass alle über dasselbe sprechen.
Top 5 Vorteile für uns und unsere Kunden
- Dokumentgenauigkeit: Unsere Dokumente sind korrekt und aktuell, da Änderungen zentral vorgenommen und Fehler behoben werden können.
- Schnellere Dokumentenlieferung: Da der Großteil des Inhalts des Dokuments bereits vorliegt und kein Kopieren und Einfügen aus anderen Dokumenten erforderlich ist, gelangen unsere Kunden schneller an die benötigten Dokumente.
- Einheitliche Terminologie und einheitlicher Schreibstil: In einem zentralen System ist es einfacher, eine einheitliche Terminologie und einen einheitlichen Schreibstil beizubehalten. Wenn wir über ähnliche Dinge auf ähnliche Weise schreiben und für ein Konzept immer denselben Begriff verwenden, können wir Missverständnisse und Verwirrungen vermeiden, die Zeit und Geld kosten können.
- Verbesserte Übersetzungsqualität: Die einheitliche Terminologie und der einheitliche Stil sorgen dafür, dass auch die Übersetzungen einheitlich sind. Wenn die qualitativ hochwertigen Übersetzungen es den Endbenutzern ermöglichen, die benötigten Informationen in der Dokumentation zu finden, müssen sie nicht nach anderer Hilfe suchen.
- Einheitliches Layout und Formatierung: Der Teleste Das Stylesheet stellt sicher, dass alle aus dem System veröffentlichten Dokumente genau gleich aussehen, sodass die Leser die gleichen Arten von Informationen leicht erkennen können.
Nächste Schritte
Derzeit veröffentlichen wir neben der Funktionsspezifikation auch unsere Wartungshandbücher und spezifischen Benutzerhandbücher im neuen modularen System. Wir werden unsere Dokumentation weiterhin überprüfen, um Dokumenttypen zu erkennen, die von einem modularen Ansatz profitieren würden.
Auch die Terminologiearbeit wird fortgesetzt. Da die Grundlagen nun gelegt und die grundlegenden Begriffe definiert sind, wird es einfacher sein, neue Begriffe einzuführen. Die neue Terminologie hat noch nicht alle unsere Dokumente erreicht, da die Implementierung der neuen Begriffe in die riesigen Mengen an Dokumentation, die wir in unseren Kundenprojekten liefern, keine leichte Aufgabe ist.
Tiina Kaarela
Tiina Kaarela
Als Technischer Redakteur bei TelesteIm Geschäftsbereich „Rollmaterialhersteller“ bin ich bestrebt, unsere Dokumentation durch die Weiterentwicklung unserer Tools und Prozesse zu verbessern. Mein Ziel ist es, dass unsere Kunden eine Dokumentation erhalten, die die relevanten Anforderungen erfüllt und gleichzeitig korrekt, konsistent und leicht lesbar ist.
Weitere Informationen finden Sie auch in den LinkedIn-Account .
