Umstellung von entwicklungsbegleitender Dokumentation auf DITA XML

Da die Produkte von NXP einen langen Entwicklungs- und Lebenszyklus haben, muss die Dokumentation für Vorgänger- und Nachfolgerprodukte und auch die Dokumentation der unterschiedlichen Entwicklungsphasen parallel erstellt und aktualisiert werden. Dies sowie die nahezu identische Dokumentation mehrerer Produktvarianten einer Familie veranlassten den Geschäftsbereich "Identification" dazu, die Dokumentationsprozesse grundlegend zu erneuern. Es wurde entschieden, XML-basierte Dokumentation einzuführen, um Inhalte professionell wiederzuverwenden und aus einer Quelle mehrere Varianten von Dokumenten zu erzeugen.

Ziel des Projekts

Bei NXP entsteht im Zuge der Produktentwicklung eine Vielzahl an internen und externen Dokumenten. Die Dokumente werden von verschiedenen Fachabteilungen erzeugt und bauen häufig aufeinander auf. Um Inhalte wiederzuverwenden, wurden häufig die Vorgängerdokumente kopiert und weiter bearbeitet. So entstanden parallele Dokumentationszweige.

Die Dokumentation wird sowohl von Entwicklern und Technikern als auch von technischen Redakteuren gepflegt und wiederverwendet. Deshalb sind einfache Bedienung der Autorenumgebung, Vorlagen für verschiedene Dokumente und eine einheitliche Informations- und Ablagestruktur entscheidend, auch für die Akzeptanz der neuen Dokumentationsprozesse.

Die Umstellung auf XML-basierte Dokumentation ist für alle Geschäftsbereiche bei NXP angestrebt. Der Geschäftsbereich "Identification" nimmt eine Vorreiterrolle ein, stimmt sich jedoch eng mit der zentralen Dokumentationsabteilung des Unternehmens in Eindhoven ab. Die neuen Dokumentationsprozesse bei "Identification" müssen sich in die Gesamtstrategie für Dokumentation und in die IT-Architektur des Unternehmens einfügen.

Vorgehensweise und Methoden

Die Umstellung auf die neue Dokumentationstechnologie und Informationsarchitektur erfolgt schrittweise. Zunächst wurde die FrameMaker-basierte Dokumentation optimiert, um Variantenmanagement zu ermöglichen und die laufenden Arbeiten bestmöglich zu unterstützen.

Für die XML-basierte Dokumentation haben wir den XML-Editor oXygen eingeführt und eine Redaktionsumgebung für die einheitliche Dokumentation, basierend auf dem DITA-Standard, entwickelt. Das beinhaltete u.a. folgende Maßnahmen:

Spezialisierung der DITA-Strukturdefinition
Konfiguration von oXygen für einfaches Editieren
Anpassung der in oXygen integrierten PDF-Transformation
Erstellung eines Inhaltsmodells für bestmögliche Wiederverwendung
Entwicklung einer Ablagestruktur für bestmögliche Wiederverwendung und Import/Export von Daten aus angebundenen Systemen
Migration vorhandener Inhalte aus Word oder FrameMaker
Anbindung von Daten aus externen Tools

Spezialisierung der DITA-Strukturdefinition

NXP verwendet eine Spezialisierung der DITA-Strukturdefinition, die konzernweit eingesetzt und von der zentralen Dokumentationsabteilung in Eindhoven gepflegt wird. Bislang wurde diese Strukturdefinition vor allem für Produktdokumentation eingesetzt. Da der Geschäftsbereich "Identification" mit der oXygen-Umgebung jedoch zusätzlich auch interne Entwicklerdokumentation erstellt, erfüllte diese Spezialisierung nicht alle Anforderungen des Geschäftsbereichs. Um eine einheitliche Lösung zu erreichen, haben wir mit den Fachabteilungen die DITA-Spezialisierung evaluiert und Änderungswünsche direkt mit der Dokumentationszentrale besprochen. Dabei ging es neben zusätzlichen XML-Elementen hauptsächlich um die Definition von Metadaten, um Informationsprodukte und Inhaltsbausteine in Zukunft besser verwalten zu können.

Bedienkomfort für Autoren: Konfiguration von oXygen

oXygen bietet die Möglichkeit, eigene Strukturdefinitionen in sogenannten Frameworks zu speichern. Mit Frameworks ist es möglich, globale Einstellungen zu speichern und gemeinsam zu verwenden. Wir haben für NXP ein eigenes Framework eingerichtet, das allen Autoren ermöglicht, oXygen in zwei Schritten so einzurichten, dass sie nach den gemeinsamen Vorgaben schreiben können.

In dem Framework haben wir viele Anpassungen vorgenommen, um den Autoren das Schreiben mit oXygen zu vereinfachen:

Automatische Einbindung der DTDs (ermöglicht das Offline-Arbeiten auf Reisen)
Eigene Aktionen (Toolbar) zum Einfügen häufig verwendeter Elemente
Einfaches Setzen von Attributen zur Variantensteuerung
CSS-Anpassung (Formulare für Metadaten und NXP-Layout)
Nutzung von Subject-Scheme-Maps zur einheitlichen Verwendung der unternehmensweiten Metadaten (Taxonomie)
PDF-Transformation per Mausklick

Automatisierte PDF-Produktion

Mit oXygen erhalten Autoren ein integriertes Framework für die DITA-Strukturdefinition. Dieses Framework beinhaltet auch das DITA Open Toolkit (DITA OT), ein Plug-in zur Erzeugung von unterschiedlichen Ausgabeformaten aus DITA/XML-Dateien. Da für NXP in der ersten Stufe zunächst nur die Ausgabe von PDF-Dokumenten wichtig war, haben wir die bestehende automatische PDF-Produktion an die erweiterte XML-Strukturdefinition angepasst. So können Autoren mit einem einzigen Befehl automatisch ein PDF im NXP-Layout erzeugen.

Dazu haben wir die XSL-Skripte des DITA-OTs zur Erzeugung von XSL-FO-Dateien angepasst. Dabei mussten wir einerseits die Layout-Vorgaben von NXP beachten und andererseits spezielle Anforderungen der Autoren für die interne Dokumentation berücksichtigen. Aus dem erzeugten XSL-FO wird das PDF-Dokument in der ersten Stufe über den in oXygen integrierten Apache-FOP Prozessor generiert. In einem späteren Schritt soll die PDF-Erzeugung über einen Antenna-House-Prozessor erfolgen; eine Lösung, die derzeit von der zentralen NXP-Dokumentationsabteilung eingerichtet und getestet wird.

Informationsarchitektur für Wiederverwendung und Standardisierung

Die Dokumentation bei NXP wurde bisher mit Microsoft Word oder Adobe FrameMaker erstellt. Für beide Tools gab es Vorlagen, die den Autoren für verschiedene Informationsprodukte eine definierte Kapitelstruktur vorgab. Für die Umstellung auf XML haben wir deshalb die bestehenden Dokumente (Informationsprodukte) modularisiert und ein Modell zur Wiederverwendung entwickelt. Dadurch entstanden neue Textmodule (Informationsobjekte), die in verschiedenen Dokumenten verwendet werden können.

Für die verschiedenen Dokumentarten entwickeln wir in Zusammenarbeit mit den Fachabteilungen standardisierte Vorlagen, u.a. für Architekturdokumentation. So ist sichergestellt, dass alle erstellten Dokumente der gleichen Kapitelstruktur folgen.

Die neue Informationsarchitektur stellt sicher, dass alle Autoren Inhalte wiederverwenden können und standardisierte Inhalte und Dokumente erzeugen.

Einbindung externer Systeme

Bei NXP werden Informationen in unterschiedlichen Tools erfasst und gepflegt. Für die Dokumentation werden viele Informationen benötigt, die aus externen Quellen stammen (zum Beispiel DOORS, einer Software für Anforderungsmanagement). Inhalte aus externen Quellen sollen in die Dokumentation eingebaut werden und den Autoren als nicht editierbare Textbausteine in oXygen angezeigt werden. Um die Textbausteine in die Dokumentation einzubinden, haben wir Zielstrukturen für verschiedene Informationsobjekte in DITA/XML definiert.

Der Austausch von Inhalten mit externen Systemen erfolgt über Skripte oder zusätzliche Tools.

Authoring Support in oXygen: CSS customization

Authoring Support in oXygen: Custom error message

Authoring Support in oXygen: Variant management

Über NXP Semiconductors Germany GmbH

NXP Semiconductors ist ein Halbleiterhersteller mit Hauptsitz in Eindhoven, Niederlande. NXP bietet Halbleiter und Systemlösungen für verschiedene Bereiche. Für die NXP Semiconductors Germany GmbH arbeiten rund 1.800 fest angestellte Mitarbeiter an den Standorten Hamburg und Dresden sowie München und Stuttgart (Vertrieb). Am Standort Hamburg unterstützen wir den Bereich "Identification" in einem langfristigen Projekt zur Verbesserung der Dokumentationsprozesse und bei der Einführung von XML-gestützter Dokumentation.