FrameMaker Single-Sourcing

[Steven Brooks <sbrooks -at- AW -dot- SGI -dot- COM>]

Although belated, I wanted to add my thoughts about FrameMaker
conditional text and installation guides. I used conditional text to
produce
four installation guides. I had to document the installation of our
product
on ORACLE or PROGRESS databases for either NT or UNIX, making four
possible combinations. Each possibility had some unique information and
some
common information.

In general, conditional text made writing fast, and, when you got used
to it,
made it easier to keep track of the unique and common information.

Here are my recommendations:

* The target guides should follow more or less the same structure in
order to come
from a shared source. If one or more of the target guides is radically
different from
the others, conditional text may not work well. In my case, I used two
sources,
based on OS, to produce the four guides. One source was NT and in it I
combined both
ORACLE and PROGRESS database instructions. The other source did the same
for UNIX.
This breakdown kept things sane, whereas intermixing OS instructions
would have wreaked
havoc.

* If whole chapters are unique, use separate book files. For example, if
a reference section
is pertinent to just one of the target books, use separate book files to
include or exclude it.

* Keep the conditional text in the same order throughout the book.

* Keep a frozen copy of the target guide separate from the source.
This practice is simply good version control. I kept separate
directories for each source and
for each target guide. (Forget about saving disk space.) When one
"flavor" was ready,
I copied the entire source directory over to a target guide directory.
Then I turned off the
conditional text, tailored the page breaks, and regenerated.

* Be careful of cross references and index entries. In general, Frame
had no problem regenerating
when I copied the source directory into a target directory.  However, I
once ran into a problem
where the references and index entries were wrong because they were
still pointing to the files in the source
directory. Like I say, it should be okay, but double-check.

* Contrary to one person's reply on the list, you don't have to change
the colors of the conditional text. Just turn off Show Condition
Indicators
when you're ready to print.


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=