Text insets: to be or not to be?

[Martinek, Carla]

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

The first couple of pages of the Preface contain the doc info (audience,
scope, purpose, structure, etc.), and the stuff that's shared among the
docs is in the latter 3/4 of the Preface. Would it work to split it into
two files (the first part with all the doc-specific stuff just set up as
a regular template, and the second part set up as a single-sourced file
that everyone could point to from their books)? 
----------

In a short, simple, answer -- Yes.  By breaking your content into
shorter topical files, you can increase their reuse.

Our general standard here is to break apart files when they have a
top-level (Heading 1, etc.) heading.  We've got 1000+ different topical
files that we can reuse between docs as necessary.  Some files can be
reused across multiple product lines; some only within product lines.

We got away from text insets because of some inherent problems we were
having with them, and build the books by linking the topical files
together.  For example, a book might look like this:

Cover
Copyright
Toc
About This Doc__FrontPage
  About_contacts_tech_support ---- (reused across all product lines)
  About_doc_conventions
Intro__FrontPage
  External_view ---- (reused within product lines)
  Media_compartment
  front_panel
  Firmware_language_modes
Operations_FrontPage
  etc.
  Etc.

We create a intro page (FrontPage) for each chapter, and then link in
the topical files behind it. It works for us.  We have one writer who
maintains all of the UG/QRG files for 6 product lines and several OEM
versions. I think at last count she was responsible for 25+ active
manuals, and by sharing the content this way, she manages to keep things
updated and meet deadlines and release dates.

We set this up with the expectation that we will be moving to structured
content (XML/DITA), and topical is the way to go for that.  Also, once
we move the topical content to XML, our Tech Support Help Desk will
easily be able to grab and reuse the content for their needs.

-Carla
 
- 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.