NETTING IT OUT

Product support content is information that your company produces to enable partners and customers to install, operate, and maintain products and services that you sell. As you expand the number of delivery channels and variations of the content itself, the complexities of producing it escalate, driving up costs and hampering efforts to bring products to market more quickly.

A proven approach to reducing this complexity is the “single-source” publishing model. It calls for an XML-aware content management system (CMS) complemented by XML-aware authoring and publishing tools. When implemented at the document/component level, this model enables the flexibility required to efficiently deliver documentation that is automatically tailored to the language, medium, and product configuration that your customers expect.

To help you evaluate potential technology providers, we’ve outlined the salient characteristics of product support content that vendors promising automation must address. We also identify the key applications that you’ll have to integrate to create a complete, single-source publishing solution that spans the entire lifecycle of product support content.

In the coming months, we plan to use this framework as a backdrop for evaluating products, such as Arbortext 5, and presenting case studies of successful cross-channel product support implementations.

CROSS-CHANNEL DOCUMENTATION:

A SCENARIO THAT CALLS FOR AUTOMATION

In our report “Cross-Channel Content Management,”1 we observed that, although content management is an important ingredient of a complete cross-channel publishing solution, it is only one of several components that make up a complete system. What kind of complete system? The management system must be complemented by, at the least, authoring and publishing tools that enable you to create and deliver your content through the various channels your organization uses to communicate with your partners and customers. We also observed that XML has emerged as a key technology facilitating flexible delivery of content across multiple media and audiences. In this report, we’ll look at a typical cross-channel publishing scenario--product documentation--and discuss the challenges presented by this content as a precursor to examining how vendors of XML publishing tools fill in the gaps left by content management systems (CMSs).

Characteristics of Documentation

Every business, regardless of industry, creates documents that help customers install, use, and maintain the company’s products and services. For some businesses, like consumer goods, the documents are short--the instructions for cooking a can of soup are right on the label. But for complex machinery, such as a car, a telecommunications switch, an oil rig, or a turbine, the documentation for operating and maintaining the equipment is much more voluminous and complex. Consider the following key facets of the documentation:

* Contains a Large Volume of Material. The manuals for complex equipment are often too lengthy to be contained in a single book. Because they are so long, such manuals are typically created by a team of writers, with each writer working on one or more portions of a manual at a time. To help facilitate that collaboration, the documentation team will break down the overall documentation set into components so that an individual writer can work on one component without interfering with other team members’ abilities to work on other components at the same time. When all of the components are ready to be published, the team assembles them into a complete set for delivery to the customer.

* Configured to Specific Products. A second facet of this type of documentation is that complex equipment is built from subassemblies and individual parts that differ according to model number. A single part might be used in a dozen or more products; likewise, its documentation must accompany each of those products. Ideally, each time the part is called for, its original source documentation is referenced and reused, rather than duplicated or rewritten. For this practice of reuse and referencing to work, the documentation components must be at level of granularity that matches part configurations.

* Translated to Multiple Languages. In addition to being long, manuals for complex machinery are typically published in multiple languages for different geographic markets. All of the relevant components of a document set must be translated from their original source language into a variety of other languages, and each revision to the material in the original language must also run through this translation process. For the complete set, this translation process may take several months, during which time the product can’t be sold to the customer. However, if the documentation can be translated at the component level, with each section translated as it is completed, then the time delay at the end may be shortened by several weeks, allowing the manufacturer to bring the product to market at an earlier date.

* Published in Multiple Media. A fourth facet of complex documentation is that it typically gets delivered not only in print, but also over the Web and possibly through other electronic media, such as CD-ROM, Help files, or handheld PDAs. In other words, the documentation gets published across multiple channels. This is what we mean by cross-channel content management. All of these versions must convey the same information to the customer, and any changes to that information made in one medium must be reflected in all of the other published versions. Because the volume of material is often very large (from thousands of pages to sometimes in excess of a million pages for a single product), converting the documents from one medium to another by hand is prohibitively slow, expensive and error prone. The same is true of the assembly process. When documentation existed only in paper, employees collated sections of custom documents manually and then numbered them by hand with a hand stamper; a sweatshop approach that invites carpal tunnel syndrome. An automated conversion and publishing system can not only shave months off of such a manual production cycle, it also reduces errors, drastically reduces costs, and makes it much more feasible to introduce changes late in the production cycle.

Applying a “Single-Source” Model

Given the facets noted above, manufacturers would like, if possible, to write and maintain their documentation sets as series of single master source files that can be configured, translated, converted, and assembled as needed for specific products. This “single-source” publishing model, in which material is written, revised, maintained, and published from a single master file, cuts the labor costs of maintaining documentation by eliminating the redundancy of maintaining master versions for each model and media format.

However, if the source files are complete documents, then it’s hard to reuse components, such as specific sections, in different document configurations. For this reason, many companies are moving toward a model of “dynamic assembly,” in which documents are broken down into discrete chunks in the repository and assembled on-the-fly for editing or publishing.

In extreme examples, like aircraft, each product is built to order, and the documentation must match the specific configuration delivered to the customer. In order for the documentation to be built “just in time,” each product option must be managed separately so that the build list for the product can also be used to create a corresponding build list for the documentation.

Industry experience over the past decade has shown that the best way to support the single-source publishing model for documentation (regardless of whether you store master documents or dynamically assemble them from components) is to maintain the text in a generic form, using SGML or XML tagging to identify the document components. SGML and XML are not specific to any media, yet they can identify the elements of the document in sufficient detail that you can automatically transform them into a variety of media. At the same time, because SGML and XML identify the individual elements of documents, you can use the mark-up to identify document components. This makes it easier to pick and choose the components you need for a specific product configuration. SGML and XML also allow attributes for each element of the document. Attributes are user definable and so are useful for identifying context, for example, marking the products to which a component belongs or marking the language in which a component is written.

System Components

A complete cross-channel, single-source publishing solution includes at least three major system components, as follows...