re-use 101

[Martinek, Carla]

-----Original Message-----

I am using Frame 8. I have a set of seven manuals that are close to 100
pages each. Many sections of these manuals are identical, some sections
differ in detail in minor ways, and fewer sections differ in more
substantial ways. Currently they are all Frame books with each chapter
being its own file within the book. There is no re-use of anything at
the moment.

This is becoming increasingly burdensome to maintain, as a change to
something that appears in all seven manuals requires me to make that
change manually in all seven files. I would like to get to re-use, or
single-sourcing, but I'm puzzled as to how to get there. Would the best
strategy be:

(a) To use conditional text and generate several versions;

(b) To try and convert everything to XML and sew things together based
on individual XML files;

(c) Something else?
I have zero XML knowledge, and whenever I read about it, my head hurts.
I am willing to learn, but the benefit needs to be commensurate with the
pain involved in learning. I'm looking for the simplest solution that
allows for some common source material using my existing Frame
configuration. Ideas are appreciated.
Joel

========================================
Joel -

I'll give you *our* solution, but you need to determine what works for
you.

We have several product lines. Each product line has its own user guide,
maintenance manual, and quick reference guide. Because the products are
similar, they share much of the content.  On top of the standard product
line, we have several custom variations of products for OEMs and
high-profile customers.

We broke our manuals apart into topical files (much like you'd do with
XML). In most cases, a topical file break came at the Heading1 level.
Within each topical file, if the content is similar enough, we use
conditional text to handle any small differences between procedures. If
a particular procedure is completely different between printers, then we
create a topical file just for that printer, and name the file
accordingly. (Example: topic1_printer1 and topic1_printer2.)

Use your book file to bring the topical files together. Our book
structure would look like this:

   Cover_page.fm
   Book_toc.fm

   Intro_front_page.fm 
   Intro_topic1.fm
   Intro_topic2.fm

   Chapter1_front_page.fm (contains chapter heading and intro paragraph,
and a mini-toc indicating what's in the chapter.)
   topic_1.fm
   topic_2.fm
   topic_3.fm
   topic_4_printer1.fm
   topic_5.fm

   Chapter2_front_page.fm
   topic_6.fm
   topic_7.fm

   IX.fm
   Back_cover.fm


This structure allows you to reuse content at the topical level across
multiple books. We have hundreds of topical files, and our conditional
text matrix has 80+ conditional text formats. When it comes to
conditional text, be logical and create your format structure before you
start applying it. In our case, we use a naming convention like this:

UG_printer1
UG_printer2
UG_printer3
(UG indicates the tagged content is for use in the User Guide of the
specific printer)

MM_printer1
MM_printer2
MM_printer3
(MM indicates the tagged content is for use in the Maintenance Manual of
the specific printer.)

We assign a color to a specific product line, and a format to a type of
manual.

Printer 1 is always purple. Printer 2 is always red, and so forth.
User Guide styles are underlined. Maintenance Manual styles are
overlined. 

So... purple text with under- and over-lines is for Printer1 and both
the UG and the MM. Red text with underline is for Printer2 user guide
only. If you apply multiple printer conditions, you'll get the standard
magenta override conditional text format, but FM8 and higher allow you
to define custom tag formats for multiple conditional text expressions.
(We aren't doing that yet, but I know its there.)

For our running headers which reflect the Chapter title, we use markers.
The variable for running header/footer 1 references to marker1. You can
insert and conditionalize multiple markers in a single file, so a
topical file could be used in chapter1 of the UG, but chapter 4 of the
Maintenance Manual.

There's a lot of info here, but hopefully you can pull out the basics
and apply it to your situation if you determine that's the way you want
to go.

Our plan is to eventually move to DITA XML. The topical structure we're
using is a good basis for that.


-Carla

***************************************
Carla Martinek, Senior Translation Coordinator/Editor
Zebra Technologies Corporation
333 Corporate Woods Parkway, Vernon Hills, IL 60061
 
- CONFIDENTIAL-
This email and any files transmitted with it are confidential, and may also be legally privileged.  If you are not the intended recipient, you may not review, use, copy, or distribute this message. If you receive this email in error, please notify the sender immediately by reply email and then delete this email.