TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
