RE: Baiting for the single source rant

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

I would like to take a slightly different tack on the single sourcing
debate. Granted you can use single sourcing techniques to produce on-line
and printed documentation from the same set of source files. Whether the
work required to implement single sourcing is more or less efficient than
authoring the printed and on-line content separately depends on size of the
documentation set and the frequency of the revision cycle.

One point that tends to get lost, however, is the cost of ensuring that the
content is accurate.

I am currently responsible for maintaining our firmware documentation. Our
firmware contains more than 100 objects and 1,200 variables that our
application engineers and OEMs interconnect to create customized control
systems. We have four versions of the firmware. We have revised each version
multiple times. All of the firmware documentation resides in a developers
manual. Keeping this manual up to date is a chore. We validate the accuracy
of the documentation each time we revise the firmware. The documentation is
checked into a revision control system and tracked along with the C++ code.
The validation cycle requires that a team of firmware programmers spend a
couple of weeks validating the code and documentation. Thus the cost of
reviewing  the information in this manual is very high.

The dilemma that I face is that in addition to the developers manual (which
contains an assortment of proprietary and public information) I need to
produce an assortment of training manuals, OEM manuals, end user manuals,
etc. All of these manuals need to contain a subset of the information
contained in the developers manual, along with new content. The challenge is
to dynamically extract (single source) this content from the developers
manual. This way, when a training manual is up for review, we do not have to
validate the content that came from the validated developers manual. In our
case, single-sourcing is all about information management, not just the
ability to produce printed books and on-line help.

I am still in the early phases of this project and am prototyping a system
that will enable us to reuse information that was validated at great
expense. This is in essence a database publishing project. If you've priced
database publishing solutions lately you know that database publishing
software is expensive, often approaching $100,000.00 and up. 

I have decided to structure the developers manual in FrameMaker+SML. I
created a special nested element to contain each variable. Nested within the
variable element are elements that store the various types of information
that we need to record for each variable, such as its data type,
description, etc. I wrote a script in the FrameScript language that finds
every Variable element in the developers manual and exports the text from
all of the nested elements to an Access database.

I then created a Database Retrieval element. This element has a number of
attributes. One attribute stores the name of the variable. Another attribute
allows the author to specify the various information types to retrieve for
that variable. I then use a second script to query the Access database and
update the content in all of the Database Retrieval elements.

I am curious whether anyone else has revision control issues to contend with
and whether single sourcing has enabled a single validated source to be used
in a variety of other documents.

Cheers,

Martin R. Smith
Manager, Technical Writing
ENCORP


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

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.