Using FrameMaker as a Single-Source Solution at Lucent
Lucent Technologies, Inc., in Landover, Maryland, is using the advanced features and functionality of FrameMaker 5.5 to implement a single-source methodology for its entire line of information products.
In 1998, Lucent acquired Yurie Systems, a telecommunications company that designs and manufactures asynchronous transfer mode (ATM) Access Concentrator systems. The Access Concentrator systems have two principal components: a chassis and a variety of input/output modules, each of which has different functionality and is interchangeable among the chassis types. The Yurie Systems product line consisted of two chassis and approximately twenty modules, but since the Lucent acquisition, the line has expanded to five chassis and nearly forty input/output modules.
The rapid expansion of the product line, combined with a renewed commitment to penetrate foreign markets, made the Lucent Landover Information Design and Development (IDD) team reconsider its documentation delivery process. Single sourcing became the ideal solution because information can be reused across a wide variety of information products; all versions are updated “on the fly,” which significantly reduces the time needed to issue each release; and our information products can be rolled out in multiple languages nearly simultaneously because translators are working at the information component level, rather than book level.
Our team of information designers and developers had several advantages when we began the single-sourcing process. The foundation document, a single master book that contained all user information about the product line, had been developed and maintained in FrameMaker. After analyzing this document, we recognized that a high percentage of existing information could be standardized, and we could ensure consistency within all documentation by having a single source for all changes.
In addition, the IDD team had a great deal of latitude and management support to reach our goal of creating a production environment that supports the single-sourcing methodology. Our greatest early challenge was to meet the deadlines associated with our product release schedule while simultaneously deconstructing our existing documentation into single-source text chunks and creating new information products.
FrameMaker has several features we use to customize our single-source material: text insets (we call them text chunks), variables, conditional text, and cross references.
Chunks and Variables
Chunks and variables are the foundation of our single-sourcing methodology. To better understand how they are used in our information products, let’s briefly compare creating a document traditionally to creating it using chunks and variables.
Using traditional production methods, standard text, such as that in the “Assembling your PSAX 1250” chapter, might be reused by copying and pasting the text into each of the five User’s Guides. Then, using a search and replace function, changes, such as the product name, would be made in each book. When the basic text does not vary much in each reuse, this traditional method works satisfactorily. However, it becomes more cumbersome as greater deviations from the standard text occur.
Now, let’s examine how text chunks are used to eliminate the need to cut and paste, as well as search and replace. To best understand the use of chunks in a document, it is necessary to think of the lowest level of granularity in a book, for example, to be a paragraph, rather than a chapter (Figure 1).
Figure 1: Illustration of single sourcing reusability
A text chunk in a template contains:
- page layout formatting
- paragraph and character tags that define typography
- all relevant text
and may contain:
- cross references,* and/or
- conditional text*
*Each of these items will be discussed in depth later in this article.
In the first stage of our single-sourcing process, Lucent’s editorial team earmarked all text that could be reused and used a template to isolate each block into an individual text chunk. All new information is also assembled using this template.
Using the example of our “Assembling your PSAX 1250” chapter, text chunks, one for each subdivision, are imported into the chapter by reference, not as text. The same text chunks then go into the first chapter of each of the five user’s guides. The “Import by reference” function works on the same principle as using non-resident graphics files in common layout applications. Just as any changes to a non-resident graphics files are automatically updated in a layout application, any changes to a text chunk are automatically reflected in any document that refers to that chunk. Importing by reference is critical to the single-sourcing methodology and is what enables “on the fly” updates.
Instead of using the search-and-replace function to change information such as the product name, variables are used for standard information such as the document number, release date, module name, and so on (Figure 2). Unspecified, generic variable definitions are inserted in a text chunk. These variables are later redefined with customized definitions within the container document. Container documents are individual FrameMaker books, which are built from our text chunks. All document customization is done at the container level. Because the variables are specified at the container rather than the chunk level, one chunk can be used by many different products, each with different document numbers, release dates, and so on.
Figure 2: Variables and conditional text: formatted at the chunk level, displayed as customized text in a chapter
Through this brief example, you can see how one of the greatest benefits of single sourcing is its flexibility. Each chunk can be used in multiple document types (brochures, installation guides, user guides, training manuals) and formats (print, Web, CD-ROM). Because all the documents use text chunks as a single source, any changes made to the text chunk are automatically applied to all container documents that use that source.
Conditional text is simply text that is tagged to display (or not) at the container document level. With conditional text, two or more product documents can use the same chunk, but each document will display only information relevant to that unique product.
For example, a user can troubleshoot problems with a module using either a console or graphical user interface (GUI). The nature of the problem is static; how users solve it varies based on what interface they are using. We create one chunk that contains both the console and GUI solutions and then assign conditional text tags to the text, enabling the console instructions to display in the console chapter and the GUI instructions to display in the GUI chapter.
We conditionalize specific text based on whether the container document is a chassis user guide, installation guide, or module user guide.
We also conditionalize text at the module chapter level to differentiate between the console and GUI interfaces that have the same functionality but different procedures and screens.
Furthermore, because the conditionalized text chunks are reused in many different documents, we use a non-printing color-coding scheme to help the writer identify and differentiate which text is meant to be displayed in which type(s) of document(s).
Cross references are standardized and implemented at the chunk level. If a chunk consists of more than one text inset (for example, module connection chunks are frequently composed of multiple procedure chunks and multiple field description table chunks), care must be taken to ensure that cross references are inserted at the primary or smallest chunk level (Figure 3). By following this procedure, you ensure that all cross references have the proper citation and page number, no matter where they occur in the container document.
Figure 3: Cross references: inserted at the chunk level, generated with the correct run scheme at the container level
Assembling the Container Document
Any information product can be quickly assembled once a sound, single-source methodology has been implemented. In addition to the text formatting procedures we’ve discussed, all of our text and graphics chunks reside in a single master folder, which is subdivided into different folders that represent the main elements of the information product content. It should be noted that it is critical that chunk files never be moved or renamed. These changes destroy the reference links the container documents depend on.
To construct a container document like a book, our production manager uses a predefined information product template. The production manager follows a content outline, developed in conjunction with the team leader and writers responsible for relevant chunks, and inserts the chunks sequentially, by reference, on a chapter-by-chapter basis. It is important to remember that chunks are imported into the container documents by reference, not as resident text files.
At the next stage, conditional text settings are turned on to display specific text relevant to the container document. The generic variables (such as document number, product name, date) that were set at the primary chunk level are redefined for a particular information product.
One thing we have learned through trial and error is that, since it is virtually impossible to predict where any single chunk will end up in the container document, headings must be inserted only at the container level (Figure 4).
Figure 4: Lucent’s single sourcing flow chart
Through the use of FrameMaker features such as text insets (chunks), variables, conditional text, and cross references, the same text components can be reused in multiple information products with various purposes.
Text chunks are at the core of our single-sourcing methodology and are essential to achieving consistency and text reuse throughout all of our information products. Because our entire information content base is maintained in one set of single-source files and imported by reference into the container documents, any changes to a text chunk will eventually be reflected in all container documents having that reference as they are printed.
In addition, because our text is formatted as chunks, simultaneous translation into multiple languages is done with greater efficiency and cost effectiveness. Translators can be provided with the latest updates, and all translation is done at the component level, not at the book level.
While most of this article has focused on the production benefits of single sourcing, our research and development process has benefited as well. The information development workload is now more evenly distributed among a team of information designers, developers, and editors. Writers are assigned to individual features, rather than an entire information product. By working in this manner, we have been able to reduce the time spent interviewing subject matter experts because much of the foundation information can be reused.
Finally, and certainly most important, single sourcing has allowed us to significantly improve the quality of our information products, resulting in improved customer satisfaction as our documentation becomes increasingly tailored to their specific needs. We are now introducing the technical publications managers at our sister locations to the specific procedures for this process.
The initial start-up effort is considerable. Company directors, managers, and documentation team members need to be educated about the long-term benefits of single sourcing, and that requires taking a whole new look at information-product development. Because upper-level management often has little familiarity with traditional production methods, we have given a series of “chalk talks” to departments we work closely with, so they have a better understanding of the capabilities and limitations of single sourcing.
Extensive training is required to aid the staff in developing consistency in writing and information product design and development. Some Information Design and Development team members had some initial difficulty migrating from the mindset and work habits associated with the “one writer, one book” environment. However, now we all work together to write and maintain an information content data base, rather than individual information products. Our staff is also experiencing a paradigm shift as we learn more about the single-source approach and how it affects team dynamics. For example, our technical review cycle is composed of two phases: an initial review at the chunk level and a final review when the information products are assembled. In this final review stage, our writers and editors ensure content and stylistic consistency. Errors made at the chunk level are corrected at this time. This task is most time-consuming when the single-source process is first implemented because of the sheer volume of new chunks.
It is important to note that lack of consistency when developing chunks can create significant problems at the container level. The chunking process itself can also be time-consuming, especially as the degree of granularity is refined.
New procedures and tools to manage our content database may need to be incorporated, because many existing methodologies support “document management” rather than “content management,” or, as we view it, management at the container, rather than the chunk level. At this time, we track critical information, such as file name, primary author, and file location, about our chunks in a traditional spreadsheet, but we remain open to the possibility that specialized software for this function may be required as our volume of chunks increases.
Finally, because our writers are performing real-time updates to the same chunks, they must all have real-time access to the LAN-resident content database and be able to consult with each other often regarding changes to the content database. Prior to implementing single sourcing, our staff was able to telecommute on a part-time basis, and files were updated on a floppy or zip disk. However, because several different writers might be making changes to the same chunk in a single day, we could not ensure that any changes made from a home office would be based on “the latest and greatest” version of the chunk. Until each writer has high-speed access to the LAN, the single-sourcing methodology cannot be implemented in a telecommuting environment.
We have found FrameMaker’s flexibility to be invaluable for our single-source documentation process. While most of this article has focused on book length files in print format, we are currently developing a procedure for using our single-source files for online help. Stay tuned!