Migration of Development Documentation to DITA/XML

All NXP products pass through long development and life cycles. For this reason, NXP needs to write and maintain documentation for old and new product versions and for different product development phases in parallel. Also, the documentation for the various versions of a product family is largely identical. For these reasons, the Identification department of NXP wanted to fundamentally renew its documentation processes. They decided to switch to XML-based documentation, which would let them professionally reuse content and create several variants of documents coming from a single source.

Project goals

When developing a product, NXP development groups generate a large number of internal and external documents. Often, these documents are incremental and interrelated. Authors would frequently copy the documents and modify them. This way, they created parallel documentation branches.

All NXP products pass through long development and life cycles. For this reason, NXP needs to write and maintain documentation for old and new product versions and for different product development phases in parallel. Also, the documentation for the various versions of a product family is largely identical. For these reasons, the Identification department of NXP wanted to fundamentally renew its documentation processes. They decided to switch to XML-based documentation, which would let them professionally reuse content and create several variants of documents coming from a single source.

Documentation at NXP is written, updated, and reused by software engineers, technicians, and technical writers. The new authoring system should offer easy handling, a unified information and filing structure, and document templates, making all users quickly adapt to the new documentation processes.

NXP intends to introduce XML-based documentation in all its divisions and considers the change in the Identification department a pioneering project. As the new documentation processes must fit into the overall documentation strategy and IT architecture, the Identification department closely coordinates the progress of the project with the Central Documentation department at headquarters in Eindhoven.

Approach and methods

Step by step, we introduced the new documentation technology and information architecture. First, we enhanced the FrameMaker technology and enabled variant management. This way, we could best support all ongoing documentation tasks.

For creating documentation on the basis of XML, we introduced oXygen’s XML Editor and developed a DITA-based authoring system for standardized documentation. This included:

• Customizing the DITA structure definition
• Configuring authoring support in oXygen
• Customizing oXygen’s PDF transformation
• Creating a content model for best content reuse
• Creating a storage and folder structure for best content reuse and file import/export from and to connected systems
• Migrating existing content from Word or FrameMaker
• Linking data from external tools

Customizing the DITA structure definition

NXP uses a custom DITA structure definition, which is maintained by the Central Documentation department and used company-wide. This definition has mainly been used to create customer-facing product documentation so far. When the Identification department started writing internal developer documentation with oXygen, it became clear that the structure definition did not cover all requirements for this information type. Together with the NXP groups, we evaluated the DITA structure definition, collected the change requests, and discussed them with the Central Documentation department. The changes mainly focused on additional XML elements and the definition of metadata to enhance management of information products and content modules.

Authoring support in oXygen

oXygen provides so-called frameworks to store customized structure definitions. Frameworks store global global settings and make them accessible for common use by authors. For NXP, we created a custom framework. Now, in only two steps, the authors can set up oXygen and write according to the same global settings.

To simplify the writing process for the authors, we adjusted the framework as follows:

• Automatic DTD integration (to work offline when traveling)
• Custom actions (toolbar) to insert frequently used elements
• Simple filling of attributes for variant management
• CSS customization (forms for metadata and NXP layout)
• Use of subject scheme maps for standardized, company-wide application of metadata (taxonomy)
• PDF transformation at the click of the mouse

Automatic PDF production

oXygen provides authors with an integrated framework for the DITA structure definition. This includes the DITA Open Toolkit (DITA OT), a plug-in that creates output in different formats from DITA/XML files. As NXP wanted to focus on PDF output during the first stage of the project, we adjusted the existing automatic PDF production to the extended XML structure definition. Now authors create a PDF document in NXP layout with a single command.

For this, we had to modify the XSL scripts of the DITA OT that create the XSL FO files. There were two things we had to consider: the NXP layout guidelines and the authors’ special requirements for internal documentation. Presently, the PDF document is created from the XSL FO file by oXygen’s Apache FOP processor. In the future, an Antenna House processor will create the PDF documents. The NXP Central Documentation department is currently evaluating this solution.

Information architecture for reuse and standardization

NXP used to write documentation with Microsoft Word and Adobe FrameMaker. There were templates for the various documents for both tools. These templates defined a chapter structure for the documents. Before we switched to XML, we modularized the existing documents (information products) and developed a content model for reuse. This way, we created new text modules (information objects), which NXP can now use in different documents.

In cooperation with the responsible NXP groups, we developed standardized templates for the different types of documents, for example, the architecture documentation. The templates ensure that all XML-based documentation adheres to a defined chapter structure.

The new information architecture guarantees that all authors can reuse content and create standardized content and documents.

Integrating external systems

The NXP groups use different tools to enter and update information. A lot of information required for documentation comes from external sources (such as the requirements management software DOORS). NXP wants to integrate information from external sources into the documentation and make it available as read-only text modules in oXygen. To enable integration of external modules, we defined corresponding DITA/XML structures for the modules.

To exchange content with external sources, scripts and additional tools are used.

About NXP Semiconductors Germany GmbH

NXP Semiconductors is a Dutch semiconductor manufacturer providing mixed signal and standard solutions for a wide range of applications. NXP Semicondutors Germany GmbH employs about 1,800 employees in Hamburg, Dresden, Munich, and Stuttgart (sales). During a long-term project, parson has helped NXP’s Identification department, based in Hamburg, Germany, to renew its documentation processes and introduce XML-based documentation.