by Michele Marques

As a technical writer, you may be exploring single-sourcing--producing multiple document outputs from a single information source--as a possible option for easing document development and production. Although solutions such as databases, SGML, and XML are available that can enable you to reuse information to produce multiple outputs, single-sourcing doesn't have to involve such complex solutions, expenses, and learning curves. Instead, if your single-sourcing needs are relatively simple, you can effectively single-source using a tool that technical writers commonly have available: FrameMaker.

This article examines how single-sourcing can ease your publication process. First, we'll look at how to single-source multiple models of the same product line. Then we'll examine how you can single-source to create different versions of the manual for different audiences. Finally, we'll explore time considerations for single-sourcing using FrameMaker. Although this article focuses on techniques to produce multiple printed manuals, you may find these techniques useful when you are producing outputs in multiple media (for example, printed manual and online help file).

Why Single-source?

Single-sourcing allows you to reuse the same content in multiple documents and/or output formats. For example, your company might have two different versions of a product ("standard" and "deluxe"), which are similar but require slightly different manuals. If this is a software product, you might have a printed manual and an online help file.

Why do you need single-sourcing? In situations where you're developing more than one document about a product or developing different versions of documents for multiple product configurations, you've likely been copying and pasting sections to move information between documents and output types. The copy-and-paste method may work for you when you are initially setting up a manual for a new version of the product. You can use the existing manual as a template of sorts for the new manual, and copy and paste relevant information from the original into the new manual.

Consider, however, what happens as you maintain the multiple versions over time. For example, when there is a change that affects more than one version, you may forget to copy that change into all versions. And when you don't forget, you are still doing twice the work--making the change in one place and copying it into the other manuals. Or if more than one person works on maintaining the documents, as is frequently the case, effort or documents may be duplicated, wasting time and money. Further, published information may differ from document to document.

Single-sourcing allows you to enter the information in one place and automatically have it appear in all documents that require it. These documents might be in different media, such as a printed manual and Windows help file. Or they might be in the same media, such as printed manuals for two similar products or for different audiences. Ideally, once the files have been set up, you should have minimal work to produce all output documents. Although single-sourcing may take additional time to set up, in the end it should save you time in publishing multiple documents. In addition, it should increase the accuracy of your publications, as there is only one place to update information.

How Can You Single-source with FrameMaker?

In the following examples, we'll walk through techniques for single-sourcing with FramMaker that describe what FrameMaker features can assist you in single-sourcing. We'll look at:

• Single-sourcing printed documents for multiple models of the same product line
• Single-sourcing printed documents aimed at different audiences

Imagine that you are writing manuals for a line of toaster ovens that has a standard oven (we'll call this one model number TO1035-S) and a deluxe oven (model number TO1035-D). What are some of the differences that could exist between the two models?

• They differ in model number. Each manual, then, would need the model number inserted with each instance of the product name.
• The deluxe model might have a "broil" function, while the standard does not. In this example, let's imagine that the "broil" function is described in its own chapter.
• The "broil" function results in additional cleaning instructions for the deluxe model. The sample recipes for the deluxe model also include recipes that use the "broil" function.

How can you set up your files in FrameMaker to single-source both manuals for both the standard and deluxe models? First, identify the requirements for each manual:

• Correct model numbers will need to be inserted throughout each of the manuals. We can do this using variables or conditional text.
• One manual will need to include a separate chapter on the "broil" function, whereas the other manual will not need this chapter. We can do this by using two book files with some shared chapters (files).
• One manual will need additional information in two places: In the section on cleaning instructions and in the sample recipes section. We can do this using conditional text.

later in this article [0].

Including an Additional Function in a Unique Chapter

In our example, the "broil" function is described in a separate chapter that should only appear in the manual for the deluxe model. To accommodate this difference between the two manuals, you can create two book files: A standard model book, and a deluxe model book. The deluxe model book includes all the chapters, including "Using the Broiler." The standard model book includes all chapters except "Using the Broiler." By including the same chapter files in multiple book files, you only have to update the shared information once.

When you are working on a manual with multiple books, you do not have to have all book files open at the same time. You can just open the appropriate book file to update, and when you update the chapter, it will be updated in all books that use that chapter (as long as all books are in the same directory, or at least pointing to the same chapter file and not to different copies of the chapter file). If I have one book file that includes all or most chapters, I find it easiest to keep that book file open when updating the manual. For example, if I were updating the manuals for the toaster oven, I would work from the deluxe model book, as this book file has all the chapters that could require updating.

Note Each book will have its own table of contents and index. As these are generated files, the only extra work is in the initial set-up of the files.

Note If you are using numbered chapters in FrameMaker 5.5.6 (or earlier), you will have to set up the numbering in each book file (for example, if chapter 3 is omitted in one book file, you would have to renumber all subsequent chapters). If you are using FrameMaker 6, if the first numbered chapter is the same, there is no extra work.

earlier in this article [0]).

Single-sourcing Different Manuals for Different Audiences

So far, you've set up your files to single-source the manuals for the standard and deluxe toaster ovens. Maybe there are now additional models, and you've continued to set up conditions and book files with different combinations of chapters to handle the additional models. It all seems so easy once you get used to it.

But now suppose that your company decides to add a new model of toaster oven aimed at kids. You decide that the kids' manual needs to be developed a bit differently. What are the differences for the manual for this model?

• It has a different model number. You can use a variable or condition to handle this.
• Some of the functions in the adult models, such as the "broil" function, are not present. You can set up another book file for this manual with the appropriate chapters, and use conditions for differences within common chapters.
• Some of the functions are limited; for example, the temperature cannot get as hot as on the adult standard model. You can use conditional text to handle these differences.
• You would like to present some of the information in a different order. For example, suppose that for the adult models, the recipes are listed in a separate chapter at the back. In the manual for kids you want to include the appropriate recipes immediately following the description of the function.

Changing the Presentation Order of Information

You can use text insets, where you import text from an outside source into a document by including a reference to it; you put in the reference (the text inset), and Frame completes the text by pulling in the referenced material. What's more, when you import text by reference, you can make updates to the text inset file to update every place using that inset.

To use text insets, you need to do two things. First, you need to break up the chapter file into smaller files. In this example the "Recipes" chapter would be broken up into

• One separate file for each recipe (or for each group of recipes that require the same toaster oven function), and
• A "Recipes" chapter, which initially would include everything from the original chapter except the actual recipes.

The manuals for the adult models would include the "Recipes" chapter, while the kids model would not.

Next, you have to set up the text insets. The file into which you imported the text is referred to as the container document. First, you will import (by reference) all the recipes back into the "Recipes" chapter. Next, you will open the chapter for each function available in the kids model and import (by reference) the appropriate recipes. As you don't want the recipes to appear at these locations for the adult models, you will select each text inset and apply the condition for the kids model. To select an inset, click once anywhere in the inset to select the entire inset. Note that conditions set in the container document determine the conditions displayed by the inset (when you are viewing or printing from the container document).

Note Text insets have some caveats. If you have heading levels that differ depending on where the inset is used, then you have to have to break up your inset into smaller insets, and repeat the headings as needed. You may also run into some bugs and annoyances in FrameMaker when using text insets; you can find answers to these issues on the FrameMaker list (sign up at http://www.frameusers.com [1]).

Using text insets can be time-consuming, and you should consider whether this is really necessary for you or whether copying and pasting might be better for the circumstances. Text insets will take more time to set up and manage than just conditional text and multiple book files.

Implementation Time

How long will it take you to implement single-sourcing using these techniques? If you begin single-sourcing with FrameMaker starting with a new project, you'll need to do some planning to determine what your outputs are. Then, using variables, conditional text, and multiple book files, it might not take more than an hour or two to set up the basic framework.

If you're working with an existing set of documents, you will need to take those steps, as well as take time to copy and paste text from the separate versions of files that you used to maintain for each manual into the new unified files and apply conditions as appropriate. This is not always straight-forward if you discover puzzling discrepancies between manuals that were not kept in sync with the copy-and-paste method. For example, if the manuals for different models of toaster oven were maintained as completely separate files for years, you could find different and possibly conflicting warnings or cautions. It will take time to resolve whether the differences in the manuals are because of differences in the models--or because changes were not copied into all appropriate manuals. Ironing out the discrepancies is time not wasted, however, as it will make your manuals more accurate.

If you are using text insets, you will need to spend additional planning time. How much time depends on how much information must be presented in a different order and whether it is possible to keep the same relative heading levels or whether they will vary. One approach is to have different style guides for different manuals so that headings look different (for example, some manuals get a flatter style which appear to have fewer heading levels), but this will only work if you can do this consistently. Otherwise you may require smaller text insets that do not include the headings.

Conclusion

For those with relatively simple single-sourcing needs, FrameMaker offers some reasonable techniques. If you are already using FrameMaker, there is no additional tool cost, set-up time can be relatively quick, and the pay-offs can be great. Using variables, working with multiple books, using conditional text, and even using text insets can allow you to repurpose information in different document outputs, as well as allow you some flexibility to develop documents for different audiences. Of course, there is only so much re-purposing you can do with FrameMaker before a database-driven solution become more appropriate--or before copying and pasting starts looking attractive again. However, single-sourcing with FrameMaker can be an effective middle-of-the-road solution that meets many documentation needs.

Michele Marques [2] has been working as a technical writer, primarily in the
software, manufacturing, and healthcare sectors. She is the List
Coordinator for the STC Single-Sourcing SIG, and is also a Dreamweaver
instructor. You can contact Michele at msmarques@rogers.com [3].

Technology [3]

• FrameMaker [3]

Writing and Editing [3]

• Writing General [3]