As a tech 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 a tech writer’s 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).
Tech Writer’s Guide: 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 does a tech writer 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.
Tech Writer’s Guide: 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 a tech writer creating 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.
Inserting Different Model Numbers
One way to set up the model number is by using a variable. In FrameMaker, you can set up variables to hold text (such as a model number) that you insert into the text whenever you need that text to appear in the document. To access variables, go to the Special menu and select Variables, where you name the variable and specify what the text should be. Note that variables are limited to holding 255 characters of text, so they are most useful for brief amounts of text that may change, such as model numbers, product names, dates, and so on.
In this example, you could add a new variable, call it “Model,” and enter the text as “TO1035-S”. Before printing the manual for the deluxe model, you would edit the variable and change the text to “TO1035-D” (the model number for the deluxe model), and the text would be changed throughout the document.
If you have multiple chapters in your manual, notice that one of the formats you can import is “Variables.” You only need to change the variable in one chapter. Then (while the chapter is still open) go to the book file, and from the File menu, select Import, then select File, and make sure that Variables is checked. You should clear the checkmarks from any other formats that you do not wish to import to all chapters.
Note: An alternative way to set up the model number is by using conditional text, as described later in this article.
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, as the tech writer, 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.
Inserting Additional Instructions in a Shared Chapter
Referring back to our example, remember that in addition to the unique chapter describing the “broil” function, the deluxe model also has additional information within chapters that both manuals will include: Cleaning instructions for the broiler and additional recipes specific to the “broil” function. You can accommodate this need by using conditional text, which lets you mark specific text to be printed for a specific manual. In this example, you could set up a different condition for each model and apply the appropriate condition to the special cleaning instructions and to the extra recipe.
To access conditional text, go to the Special menu and select Conditional text. First you need to add the conditions. If you are using conditions only to indicate text specific to the deluxe model, you only need to add one condition. If you are also using conditions to indicate text specific to the standard model (such as the model number), you will need to add conditions for both models. As you’re developing conditions, keep in mind that conditions work best when they are only for one purpose (for example, different hardware lines); otherwise, you may have to use additional conditions to handle all combinations (for example, standard-online, standard-print, deluxe-online, and deluxe-print).
How should you name your conditions? I generally create one condition per manual. In this example, I would create one condition for standard and another for deluxe. But there are alternatives that might make sense for you. For example, if two “extra” functions in the line of toaster ovens (“broiler” and “self-clean”) that result in four models (standard, self-clean, and broiler, as well as a deluxe model that includes both broiler and self-clean), you might decide to use two conditions (one for each function) and then show one or both conditions as required for the manual being printed.
Keep in mind that in FrameMaker, conditions are combined with logical OR statements (to those who are comfortable with Boolean logic). This means that if you have conditions for model and conditions for media (for example, standard, deluxe, print, and online), that showing one set of conditions will show all text marked with any of those conditions. For example, showing “standard” and “online” will show all text tagged as “online” (whether it is also tagged for “deluxe” or not), as well as show all text tagged as “standard” (whether is also tagged for “online” or “print”).
Once you have set up the necessary conditions, apply them to the text by selecting the text, and then applying the condition. You can more easily see what text has associated conditions by setting condition indicators (such as colors, change bars, or underlining), which mark text accordingly as having a condition. Note that if you have two different conditions set with two different colors as condition indicators, text set to both conditions will show as magenta. In this case you can only check which condition is set by selecting the text (or clicking in the selection) and checking either the status bar or the conditional text window (if it is open).
Finally, before printing, show or hide the appropriate conditions and turn off condition indicators. These conditional text settings must be applied to all chapters in the book, but you can import this setting as a format from one file to all other chapters. You must also re-generate the table of contents, index, or any other generated files, as the page numbers may change when you show or hide conditions.
Note: You could also use conditional text to indicate the model number (instead of using a variable, as described earlier in this article).
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).
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.
Tech Writer’s Guide: 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.
Tech Writer’s Guide: 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.
Ready for Part II? Right this way
