Single-Sourcing with FrameMaker: How do I do it? (long)

["Michele Marques" <marquesm -at- autros -dot- com>]

I originally responded privately to a private query, but see another query
on the list as to "how do I do it"?

There are three different techniques I use for single-sourcing:

(1) Conditional text. For manuals that share the same chapters and
information in the same order, this is enough. This might be the case for
two different hardware devices with slight differences. Note that for these
manuals with slight difference, I use 1 (ONE) book file, and, of course, the
same chapter files.

(2) Multiple book files. For manuals that do not share the same chapters,
each manual has a separate book file with the appropriate chapters. This is
usually combined with conditional text and sometimes text insets (see
below). You still do not have to have multiple 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 copies of the chapter file).

(3) Text insets. Sometimes information within one chapter must be presented
in a different order for two different manuals - or the same information
must appear in two different chapters. When you import text "by reference",
this is called a "text inset" within FrameMaker. Conditions set in the
container document determine the conditions displayed by the inset (when you
are viewing/printing from the container document). 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. There are some bugs and annoyances in FM when using text insets, but
you will find various answers to these issues on the FrameMaker list.

If you need to go with #3, consider whether this is really necessary for you
or whether copy and paste might be better for you. This will take more time
to set up and manage than just points #2 and #3. Also, if you are tempted to
re-use information in very different guides (that maybe were started in
different directories), you may end up with the frustrating situation of
trying to synchronize files (for text and images) between two directories.

In terms of time to implement:
If you are only using techniques #1 and #2, it shouldn't take more than an
hour or two to set up the basic framework, once you know the outputs you'll
need and combinations of outputs. The length of time it takes to copy/paste
text into the new unified files and apply conditions as appropriate depends
on the amount of text you have, and how long it takes what outputs to get
what texts (not always straight-forward if you discover puzzling
discrepancies between manuals that were not kept in synch with the
copy/paste method).

If you are using technique #3, you will need to spend more 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. Note that you could have different style
guides for different manuals so that headings look different (e.g., some
manuals get a flatter style with fewer heading levels), but this will only
work if you can do this consistently.

Note 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 audience and conditions for media (e.g., doctor, nurse,
pharmacist, print, on-line), that showing  one set of conditions will show
all text marked with any of those conditions. For example, showing NURSE and
ON-LINE will show all text tagged as ON-LINE (whether it is also tagged for
NURSE or not) as well as showing all text tagged as NURSE (whether is also
tagged for ON-LINE or PRINT). This is probably what Andrew meant when he
described the system as being clumsy and a kludge.

Conditions work best when they are only for one purpose (e.g., different
hardware lines); otherwise you may have to use more conditions than you want
(NURSE-ONLINE, NURSE-PRINT, DOCTOR-ONLINE, DOCTOR-PRINT, etc.).

There is only so much re-purposing you can do with FrameMaker before a
database-driven solution become more appropriate - or cut/paste starts
looking attractive for certain variants.

------------------------------------------------------------------------
Michele Marques, Technical Writer
AUTROS Healthcare Solutions, Inc.
marquesm -at- autros -dot- com <mailto:marquesm -at- autros -dot- com>

This material is intended for the use of the individual
to whom it is addressed and may contain information that
is privileged, proprietary, confidential and exempt from
disclosure. If you are not the intended recipient or the
person responsible for delivering the material to the
intended recipient, you are notified that dissemination,
distribution or copying of this communication is strictly
prohibited.
If you have received this communication in error,
please contact the sender immediately via e-mail and destroy this message
accordingly.



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

  +++  Miramo -- Database/XML publishing automation.  See us at  +++
  +++  Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion  +++
  +++ More info: http://www.axialinfo.com  http://www.miramo.com +++

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.