Using DITA in the Product-Development Life Cycle

Home/Publications/CIDM eNews/Information Management News 02.14/Using DITA in the Product-Development Life Cycle

JoAnn Hackos, Comtech Services, Inc.

Based on inquiries we conducted through LinkedIn, presentations at the Content Management Strategies and Best Practices conferences, and discussions with a few key individuals, we have found a lot of interest but very few examples of organizations that are successfully reusing content throughout the product-development life cycle. Those examples that we did encounter are either just getting started or are focused on a specific type of content that is more easily automated.

While the results of the study were somewhat disappointing, the potential for content reuse, especially using an XML-based language like DITA, is considerable. A few successful companies have provided key guidelines that information-development managers should find promising.

Potential for Content Reuse

Let’s start by defining the potential of content reuse in product development. Both hardware and software projects ordinarily begin with requirements documents that define the customer need for a new product or an enhancement to an existing product. In an agile development environment, these requirements might be written as user stories. In more traditional waterfall development, formal requirements documents may account for the user problem to be solved.

In a waterfall environment, design documents and specifications further define what will be produced. These documents may include descriptions of planned product features and functions, information that might eventually become part of documentation deliverables for the customer.

In an agile environment, with less written down, the design concepts and specifications may be embodied in an expansion of the user stories, details included in the product interface, or notations in the software code itself.

In hardware development, much information about the design may be captured in detailed design documents and in CAD drawings.

Much of the information generated may never be suitable for external customers because it is directed toward developers not users. But some of the information may be used by internal “customers” farther along in the life cycle. System testing, for example, often uses information from product developers to develop test scripts.

Most likely, the primary internal customers for product information will be the technical writers who must transform it into information appropriate for external customers. Much of the time, the transformation is extensive since external users want to know how to use new features and functions in their products, not how they were designed and developed. However, information exists that is likely to be applicable and appropriate for reuse.

For information developers, the key is finding where the information resides, who is responsible for its development, and whether it can or should be transformed for use in either internal or external customer information.

Auto-generated Content Implementations

Perhaps the most promising area for information reuse is reference information. However, an important requirement for automation is that source and destination by an XML-compatible format. If engineering data is already XML-based, it can be automatically transformed to the DITA standard. If it isn’t XML-based, it may still be transformed but may require more programming skill.

During the study, we encountered several excellent examples of auto-generated content. I’ll summarize our findings here without identifying the companies by name.

Company One found that copying and pasting command and API content from engineering PERL modules was both time-consuming and fraught with potential errors. In their new process, the writers reviewed and commented on the descriptions in the PERL modules, which were then reviewed by the engineers. They then generated the command reference manual completely from the PERL module source.

As a result, they had a single-sourcing solution that provided the quality of the command descriptions, eliminated inconsistencies, increased productivity, reduced man hours in maintaining consistency, and above all enhanced the user experience.

Company Two implemented a similar process to automate their Data Dictionary. The engineers wrote field descriptions in their software code using a custom DTD. The writers edited the descriptions for clarity and good English. The strings in the source code were then extracted into DITA. With the addition of introductory topics developed by the writers, the entire Data Dictionary was generated in about 40 minutes.

One benefit that Company Two encountered was the enthusiastic participation of the engineers in XML authoring. They were happy to end use of unstructured FrameMaker and work directly in XML.

Company Three developed machine-readable design documents that could be automatically filtered for different internal customers, increasing content reuse and extending the value of the technical writing teams. Customer-facing documents and documents for the testing team are generated from the same source, greatly reducing the time to market for the product and the required information.

Sophisticated Reuse Implementations

Perhaps the most interesting and sophisticated development of a complete content reuse program throughout the product-development life cycle comes from Freescale. Bob Beims, who originated much of this implementation, wrote about the Freescale IDEA project for the CIDM Best Practices journal.

The first step in Freescale’s development of the IDEA project was an analysis of existing processes that clearly demonstrated that information developers were losing productivity. Writers were spending time transferring information in design documents into user documentation, often resulting in content that was much too late to affect downstream processes like product testing. As Bob points out, the content was in multiple repositories and hard drives and was in multiple formats that made reuse impossible. Time spent converting information from one format to another was tedious and counter-productive.

In developing the IDEA project, Freescale identified ways to move content directly from its source to its users without duplicating effort. Once they had improved the flows for information that became part of customer documentation, they were able to extend their IDEA to information being developed as part of engineering and testing. They have made information development the foundation activity for every step in the process from initial requirements to final manufacturing.

All parts of the organization now use the same centralized CMS and XML processes rather than traditional software development systems. As a result, all the information needed throughout the product-development life cycle resides in one place. Because the content is together and all in XML, Freescale information developers can easily and quickly generate tailored sets of content for internal and external customers. Information development is now an integral part of the product design process. Not only does the integrated process save time but it ensures that content is accurate and of high quality.

In addition to reuse and customization, the IDEA project has resulted in requirements traceability by leveraging native XML capabilities. They found that all content could be traced back to a root source, especially when that root information is highly structured.

Information developers are able to produce information that enables the customers’ success. They are more customer-focused, asking customers to review early drafts of content, holding meetings with customers that focus on information deliverables, conducting customer satisfaction surveys, and implementing standards.

By eliminating redundancies in information design throughout the process, Freescale has reduced cycle time, which translated to faster delivery of products to market. And faster delivery is accompanied by high quality and improved customer satisfaction. They have developed cycle times never before seen in the semiconductor industry.

Obstacles to the Reuse of Content Across the Product-development Life Cycle

The primary obstacles mentioned by contributors to this study, especially those who added comments to the LinkedIn posting are these:

  • Entrenched practices, processes, and tools used by different groups within the organization
  • Lack of tools that make information development straightforward and simple by all individuals involved in the product-development life cycle
  • Lack of a single integrated tool set across all organization groups
  • Lack of a high-level champion who is able to bring the organization together to support a quality improvement that will reduce costs, improve quality, and improve traceability

The advantages of developing and reusing content in one integrated process are clear, but cultural issues and the lack of high-level management support are difficult impediments for many organizations to overcome. Those that succeed experience results of the magnitude that have been demonstrated at Freescale.

Methods for Overcoming the Obstacles

Several methods of overcoming obstacles became apparent in the course of this study:

  • Respond to initiatives begun by other parts of the organization. If the engineering team wants to move to their own version of an XML DTD, you will find that by working closely with them you will be able to develop a process that allows them to convert engineering content into DITA for review and potential reuse.
  • Demonstrate the cost of doing things without collaboration. Freescale found that the technical writers were spending nearly 70% of their time doing other things than writing. The reasons: content was scattered in multiple repositories, making reuse impossible; content was stored in binary file formats with presentation woven into the content, making conversion expensive and time-consuming.
  • Research the content that can be best reused and traced through the lifecycle. Some companies found ways to take reference content from sources that could be automatically transformed into DITA and publications. Freescale analyzed exactly where each information object needed for customer publications was sourced to get to the root information. Then, they found a way to stream the root information directly to the consumer without unnecessary stops along the way. The information is reused all along the lifecycle, including in testing.
  • Demonstrate the cost savings. Freescale was able to generate 30 sets of customer-tailored documentation, roughly 60,000 pages, from 3,000 pages in a single-sourced content set. They cut the time to produce from two to three weeks, to less than four hours.
  • Enlist the help of a high-level champion. One company found that the support of the Vice President of Research and Development and the leader of the documentation team, a former R&D engineer, was essential to the success of their quality initiative. High-level champions who are situated in positions that give them leadership across domains is crucial to success.
We use cookies to monitor the traffic on this web site in order to provide the best experience possible. By continuing to use this site you are consenting to this practice. | Close