The Advantage of Text Insets (was: To single source or not?)

[Dan Emory <danemory@xxxxxxxxxxxx>]

At 02:14 AM 10/2/00 +0000, teknicol@inter.net.il wrote:
>I have a few questions that have been bothering me...
>
>Single sourcing seems a great idea to technical writers that are under
>tremendous pressure. You write one source document and then use it - maybe
>with some modifications in conditional text - to create html help, html
>etc.
=============================================
Since you're using conditional text, I assume that your DTP is FrameMaker.

The trouble with single sourcing is that it usually forces you to make
design compromises and tradeoffs in order to meet the often diverse 
requirements
of the different target outputs/formats. In particular, a well-designed
on-line help system with powerful navigation capabilities is often in
harsh conflict with other deliverable outputs (e.g., printed output).

My advice is not to use a single-sourcing approach if the dictated
requirements for different deliverables force you to severely compromise the
usability of the on-line help (or any other deliverable for that matter).

One alternative is to heavily modularize the content, creating a separate
FrameMaker file for each module. You use Frame's conditional text feature
to deal with the variations in content/format for each deliverable.
Each such module becomes a FrameMaker text inset.

Then, for each deliverable, you create a separate template, and
construct from the applicable template a "skeleton" document that
mainly contains the headings and "glue text" for each deliverable.
The conditional text settings in each skeleton include the show/hide
settings that are appropriate for the associated deliverable.

Now, you import the applicable modules as text insets into each skeleton
document. These text insets will take on the show/hide conditional text 
settings of the
skeleton. If the text insets are imported by reference, then all the
skeleton documents are auto-updated whenever you change the content
of any of the modules.

As you can see, this approach allows you to have wide variations in the
structure and formatting of the different deliverables, thus avoiding many
of the compromises that can negatively affect usability.

The text inset/skeleton document approach described above not only helps
to make a single-sourcing approach more viable, it also solves many of the
problems associated with a collaborative authoring environment.
In such an environment, each writer would be given responsibility for
a set of modules instead of entire document files, and lead writers have
responsibility for the skeleton documents. Each writer can create/update
each of his/her assigned modules in separately named text flows within a single
FrameMaker "fragment" file. In that case, each named text flow becomes
a separate text inset.

The text/inset/skeleton document approach is also ideally suited for
use in a proposal environment.

Note also that this approach provides an excellent means for asseting
version control below the document file level. Each individual module can be
separately controlled. At the final production point, all of the text insets
are converted to ordinary text (thereby freezing the document's
configuration), and the version of each module that existed at the
freeze point is recorded.


====================
| Nullius in Verba |
====================
Dan Emory, Dan Emory & Associates
FrameMaker/FrameMaker+SGML Document Design & Database Publishing
Voice/Fax: 949-722-8971 E-Mail: danemory@primenet.com
10044 Adams Ave. #208, Huntington Beach, CA 92646
---Subscribe to the "Free Framers" list by sending a message to
majordomo@omsys.com with "subscribe framers" (no quotes) in the body.



** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **