RE: object-oriented documentation

Subject: RE: object-oriented documentation
From: "Smith, Martin" <smithmr -at- encorp -dot- com>
To: "'Anonymous Poster'" <anonfwd -at- raycomm -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 14 Dec 1999 10:25:21 -0700

This is a subject of particular interest to me. I am responsible for
maintaining our object-oriented firmware documentation, which is based on
the ECHELON LonWorks standard. We have a base set of about 120 objects and
1200 user-accessible variables called SNVTs (sni-vits).

I maintain a reference manual that provides detailed information about each
object and its corresponding variables (SNVTs). Each of our various products
contains a different assortment of objects and SNVTs. The question then
becomes how to produce manuals for the various products when so much of the
information is redundant. Another challenge is to validate that a given
product manual contains all of the objects and SNVTs associated with the
product. Finally I need a way to detect when new objects and SNVTs are added
to the firmware.

One solution that comes to mind is to use Frame's conditional text feature
to produce the various product reference manuals. However, this solution is
highly prone to error and difficult to validate. It is unlikely that all of
the conditional text settings would remain accurate and synchronized with
the product after more than a couple of revision cycles. Furthermore, Frame
does not allow one to control conditional text settings at the book level.

I have seen demos of expensive database publishing systems that handle tasks
such as this using SGML, but such systems are way beyond our budget and are
overkill for the project.

What I decided to was solve the problem using FrameScript (a 149.00 object
oriented scripting language based on Frame's C language API:
http://www.frametools.com/).

Here's how it works. Each of our products is capable of automatically
generating a text file listing all of its objects and SNVTs. I keep copies
of these files on my computer: one list for each product. I wrote a script
that parses these lists and validates that the reference manual contains all
of the objects and SNVTs listed in the text file. If an object or SNVT is
missing, the script displays an error message and automatically adds a
heading for the object or SNVT in the reference manual.

The reference manual uses two conditional text settings: on and off. When I
want to generate a manual for a product, I run a script that prompts for a
text file and then does the following:
1) The script walks through each file in the book and sets the conditional
text settings for all paragraphs to off.
2) The script then parses the input file, finds the corresponding objects
and SNVTs in the reference manual and changes the conditional text settlings
for those paragraphs to on.
The end result is a conditionally tagged book that is guaranteed to match
the product exactly.

I have also written scripts to parse our C language source code and extract
SNVTs, objects, and the corresponding comments; automatically add FrameMaker
index entries; and convert FrameMaker books to dynamic HTML. I am currently
writing scripts to convert our manuals to Microsoft HTML Help.

Just a few examples of what one can accomplish with a little script writing.

Have fun.

> Martin R. Smith
> Technical Writer / Audiophile
> ENCORP: The Energy Automation Company, http://www.encorp.com
> (970) 686-2017 x 223




Previous by Author: PowerPoint to Illustrator
Next by Author: PDF back to Word
Previous by Thread: Re: object-oriented documentation
Next by Thread: RE: FWD: object-oriented documentation


What this post helpful? Share it with friends and colleagues:


Sponsored Ads