Structured docs or conditional text

[Callie Bertsche]

Hi Carl, 

Depending on the amount that your installation instructions differs
between platforms, you may want to consider using separate docs with
text insets (and variables, if appropriate) in addition to
conditionalized text. I have found that for sections of the installation
steps that vary only in product name, you can cut the text, put it in a
separate document, refer to the product as a variable (example:
"navigate to the [product] installation folder..."), and then import
that file as a text inset. Repeat for each large chunk of nearly
identical sections. Whether this is a good solution depends on your
preference and the way your material varies.

If you go with conditional text, I recommend conditionalizing by whole
sentences or whole phrases, rather than letters or words. It will reduce
the brain power you have to use to make sure all the spacing/grammar is
correct. :)

Cheers,

Callie Bertsche

Tecplot, Inc.

 

From: framers-bounces at lists.frameusers.com

[mailto:framers-bounces at lists.frameusers.com
<mailto:framers-bounces at lists.frameusers.com> ] On Behalf Of Carl Yorke

Sent: Tuesday, March 24, 2009 5:11 PM

To: framers at lists.frameusers.com

Subject: Structured docs or conditional text

Hi All,

I came to tech writing late in life (ten years ago), so there's a lot

about it, and technology, that doesn't come naturally.

I want to single source my install instructions. All outputs right now

are PDF, but I need to document how to install our product for

production, for QA, and for demos. In addition, the install instructions

vary depending on the hardware. 

Conditional text seems awfully complex for this situation, and I don't

even know if using structured FrameMaker is a possible solution. 

Any thoughts?

Thanks,

Carl Yorke