Case study: Freescale Semiconductor Inc

To deploy authoring solutions tailored to the specific needs of the different documentation contributors, Freescale has taken full advantage of oXygenXML’s:

• Ease of configuration and customization
• Strong DITA feature support
• General ease of use

Using oXygenXML’s sophisticated framework feature and framework package manager, Freescale has removed the need for authors to individually manage the various software tools required to accomplish their various authoring tasks.

Where They Were: A Tools Tower of Babel

Freescale’s initial XML implementation used multiple products for authoring XML, one tailored specifically for use by engineers, full oXygenXML for dedicated technical writers, as well as non-XML word processing and desktop publishing tools.

Freescale has over 70 dedicated technical writers and several-hundred design engineers distributed around the globe. Freescale’s documentation is centrally managed in a component content management system (CCMS).

The engineer-specific authoring tool was configured to be “simple”, providing a limited set of features in order to be as much like a word processor as possible. However, many engineers quickly found the tool to be too simple for their needs or too difficult to use. They were unable to create complex document structures such as sophisticated tables.

Technical writers had full-featured oXygenXML but it was not adapted to the details of Freescale’s specific documentation requirements. It offered features and options that were simply not relevant to Freescale’s writers, such as templates for topic and map types that Freescale did not use and did not want to use.

In addition, all contributors, both design engineers and technical writers, were responsible for managing their tools themselves: getting software updates, managing license keys, configuring options, etc. For engineers in particular, for whom documentation was a small part of their jobs, this software management overhead was a significant pain point, limiting their enthusiasm for contributing to the documentation.

Some engineers installed and configured oXygenXML in a way that wasn’t consistent with or integrated with the rest of the Freescale system. This creativity made it difficult or impossible to support them, rewarding their enthusiasm with frustration.

The various authoring tools were also not well integrated with Freescale’s component content management system, making it difficult for authors to get content into and out of the central content repository.

Assessing these pain points, Freescale agreed with the documentation contributors that a single authoring tool was needed to support all the tasks authors perform. This tool must be better tailored to the needs of the different user groups.

The Solution: oXygenXML Tailored and Centrally Managed

Freescale evaluated a number of candidate XML authoring tools and chose oXygenXML because of the following strengths:

Flexibility and range of extensibility

• A full set of features from which to choose (but also easy to hide when not needed or wanted)
• Ease of integration with CCMS systems through oXygenXML’s plugin architecture
• oXygenXML’s framework manager, which makes it possible to centrally manage distribution and update of oXygenXML frameworks
• Cross-platform support (Freescale has contributors on Windows, Mac, and Linux machines)
• Attractive price

Freescale staffed a full-time team of three to implement and manage the authoring environment: two software engineers and one trainer/customer advocate.

The team’s first task was to interview users and gather requirements. Using these requirements as a starting point, they mocked up potential authoring tool designs and worked with focus groups to review and refine the designs.

The team developed two editor configuration designs: one tailored to design engineer contributors and one for dedicated technical writers.

Using Oxygen’s framework feature, they developed separate frameworks with customizations that tailored the oXygenXML user interface and feature details to the needs of each user type. This tailoring allows Freescale to provide exactly the features and functions the writers require and nothing they don’t.

They developed an installation tool that manages the installation and update of oXygenXML on writers’ workstations, simplifying the task of managing the software itself.

They use oXygenXML’s package management service to manage distribution and update of the Freescale-specific oXygenXML packages. This eliminates the need for individual authors to manage updates and editor configuration details. It also allows for iterative improvement to the authoring environment as well as coordinated distribution of new features and fixes.

As part of this effort, the team implemented an oXygenXML plugin to integrate with their CCMS. The team identified the key actions that users need to with the CCMS, making oXygenXML the single point of contact for all authoring tasks. The oXygenXML team can produce new, thoroughly regression-tested updates every quarter or so.

Where They Are Now: Contributors are Much Happier

The new oXygenXML-based system was rolled out at the beginning of 2014. Between January and November 2014 about 300 users have been trained on the system, most of whom were new to the XML-based process, the Freescale CCMS, and oXygenXML.

Response to the system has been very positive and many of the newly-trained design engineers have become advocates for the system.

By resolving on a single authoring tool platform Freescale has greatly reduced the tools chaos of the past.

The ability to fully configure and customize the oXygenXML interface and feature sets makes it possible and practical to optimize the authoring tools for each type of author. The ability to centrally manage the deployment of oXygenXML configurations makes it possible to quickly respond to new requirements and author feedback, helping to avoid author dissatisfaction and a desire to seek out different tools.

The effort the Freescale team put into engaging the authoring community and providing training and other support helped to ensure acceptance and productive use of the new authoring system.

By focusing on simplifying the software installation and maintenance processes, Freescale addressed a major point for authors, making it much easier for all authors, but especially occasional authors, to contribute to the documentation.

Some quotes from Freescale uses:

"My productivity has gone straight up since I started using Oxygen.” ­ John Honnold

"The Outline view empowers me to complete work before the deadline. Using this view, I can swiftly access a single register in a long file, display its bit fields, and edit them with ease in the Editor view.” ­ Noreen McMahan

"I like my XML raw and not GUI. oXygenXML remains my go-to tool for editing and validating XML content. “ ­ Jo Spall

Where They Are Going: The Future for Freescale

Freescale continues to refine and extend their oXygenXML-based authoring environment. Their regression tests allow them to quickly evaluate and deploy updates to oXygenXML, and to stay current with new features, which is especially important as Freescale moves to implement more DITA 1.2 and 1.3 features in their documents.

Summary

oXygenXML’s unique features, especially the ease of customization and the package manager, coupled with oXygenXML’s overall strength as an XML editor, have enabled Freescale to address the many pain points faced by documentation contributors. Freescale has reduced or eliminated the tools chaos. In short, Freescale’s move to oXygenXML has made life easier for authors, allowing them to focus on the task of writing, not the task of tools management.