Re: Frame Conditional Text

[Glen Accardo <glen -at- SOFTINT -dot- COM>]

> My company's product runs on multiple platforms, e.g. DOS, UNIX, VAX/VMS,
> NT, etc. The system administrator guides (or system configuration
> guides) for each of these platforms contain upwards of 80% identical
> information.  Previously, we managed separate documents for each platform.
> Changes in the product configuration meant identical changes in X number
> of separate documents.

> With conditional text, we (hope to) have one document with the conditions
> handling the platform specific stuff. When a change occurs in the product,
> one change is made in the documentation. This also makes it easier for
> one person to manage the configuraion guide (notice, not guide*s*) as
> it's just one document, not five.

I've got exactly the same situation: essentially the same text in three
different manauls -- MS Windows, X Motif, and UNIX/VAX systems.  In theory,
when I need someone to, say, check the contents of the directory, I could
have conditional text for [DIR]{ls}(DIR).  All is fine and good, check
one setting and off you go with the right stuff in the manual.  Not quite.

For one thing, regardless of what product adminstrators say, products on
multiple platforms are NOT identical.  One program may have three features,
and another has five.  You'll find your conditional text getting nastier
and nastier, or you'll start writing around situations involving numbers/lists.
That is, instead of saying "blah has five features: 1, 2, ...." you'll
say "blah has the following features: 1, 2 ...."

Second, Framemaker doesn't have conditional formatting.  Getting back to the
one has three the other has five example, you'll find that page breaks will
often land in different places.  One thing I'd like to do is specify
"when X is selected, this paragraph has a page break, otherwise, it doesn't."
You may find yourself either compromising pagebreaks, making non-conditional
text conditional to handle the page breaks, or reformatting manually.  All
of these has a cost, so be careful which one you use.

A third item to consider is names of things which can be made generic.
MS Windows users receive diskettes, while everyone else gets a tape.  Rather
than make every occurance of diskette conditional, I switched to "distribution
media."  It ain't the best, but it's always correct and doesn't affect
page breaks and such.  Also note that swithcing between diskettes/tape is
also a switch in number, so you have to switch the verb too -- or make the
entire sentence conditional.

Another thing I've had to do is maintain certain instructions in separate
chapters.  Installation is completely different in every case, so I have an
install chapter for each platform -- much of the text is identical, but
is short so maintenance is not so bad.

------------
glen accardo                         glen -at- softint -dot- com
Software Interfaces, Inc.            (713) 492-0707 x122
Houston, TX 77084

Did the Corinthians ever write back?