Eliminating duplicate information in documentation sets

["Smith, Martin" <martin -dot- smith -at- encorp -dot- com>]

Hi all,

I am looking for an effective way to eliminate duplicate information in a
library of firmware documentation. Solutions that I am considering involve
FrameMaker+SGML or FrameMaker plus an add-on database component.

Background:
I am responsible for documenting the firmware that we embed on a line of
generator power controls. These are large circuit boards with input
terminals, output terminals, EPROMs, memory, and two microprocessors. Our
application engineers and OEMs create customized control systems by
connecting our various firmware objects through a process called binding.
The control contains approximately 200 objects and more than 1,200 variables
that can be bound together. We currently have four different versions of the
firmware and multiple revisions of each version. We need to provide detailed
information about each variable and each object.

The problem:
I need to produce an assortment of manuals that contain information about
the variables and objects. The objective is to produce a controlled, master
document that describes each variable and object. All subsequent manuals
should import information about variables and objects by reference from the
master document. Doing this successfully would eliminate the maintenance
nightmare that occurs when thousands of chunks of information are duplicated
in a multitude of different manuals. In addition, I need to conditionally
tag the variable and object documentation in the master document in order to
expose or hide information, and thus produce books for various target
audiences.

Options that I have considered:
One option would be to create a separate Frame file for each variable and
object and then import these files as needed into the various manuals as
insets. This would result in around 5,000 Frame files that we would need to
import as insets, a task that we could automate to some extent with
FrameScript. We could then use a revision control system to control the
various revisions of the variable and object documentation files. The
downside to this approach is simply the complexity of working with thousands
of individual Frame files.

Another option would be to structure the master document using
FrameMaker+SGML. I was hoping that I could then create one master document
rather than 5,000 or more individual Frame files. I was hoping that I could
then import information into the various manuals by creating a cross
reference to a given element (variable). However, from what I have read so
far, FrameMaker+SGML does not allow you to create a cross reference that
pulls in an entire element and all of its descendants. A cross reference to
an element only pulls in the text up to the first paragraph. I am reading
about creating document entities in FrameMaker+SGML which are imported into
other FrameMaker+SGML documents as insets. From what I have read, document
entities may seem like a workable solution but I am not sure how they would
be used in practice. Can anyone offer any suggestions or clarify how
entities function in a FrameMaker+SGML environment?

Yet another option would be to store the object and variable documentation
in an ODBC compliant database and use an add-on product like Pattern Stream
to populate the various manuals. The ODBC-compliant database (Access for
example) would store the approved documentation for the objects and
variables. I can see two problems with this approach. First, Pattern Stream
does not allow FrameMaker to populate the database, so I would need to
design a front end to populate the database. Second, I am not sure how the
database would handle the meta data needed to indicate paragraph styles,
character styles, and conditional text.

I am assuming that going the database route would require a full-blown SGML
application with the database storing SGML-tagged text. Unfortunately I do
not have the budget or resources available for a full-scale solution.

If anyone has any suggestions for handling this problem I would really
appreciate hearing from you.

Thanks,

Martin R. Smith
Manager, Technical Writing
ENCORP
9351 Eastman Park Drive
Windsor, CO 80550
970-674-5223
martin -dot- smith -at- encorp -dot- com



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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

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/

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