Consistent Terminology AND Single Sourcing AND Tools

Subject: Consistent Terminology AND Single Sourcing AND Tools
From: "Guy K. Haas" <ghaas -at- selectica -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 16 May 2000 10:11:03 -0700

In brief:

I'm documenting 5 APIs. One for Java, and two each for COM and C.
The Java one can be documented from the JavaDoc.
The COM PI is actually a wrapper around the C API.
The C (and, hence, the COM) comes in two variants--one returns
structures and one returns XML strings.

Still, there is a HUGE amount of identical text across the COM
and C documents. In fact, there is a good bit of overlap within
each doc, because some arguments occur in almost every function
and some occur in several, with the same description each time.

I am using conditional text to produce the two versions of the
C document. Once that became stable, I made a copy of it and
changed all the names of data elements and function names to the
COM version, and replaced C code samples with COM examples.

NOW comes maintenance. New functions are being added. Old
functions are being extended. Descriptions are being amended.
So I must go through the C document file, making additions and
consistent changes to the repeated material, then go through
and make the same changes in the COM document file. Tedium!

Has any of you made extensive use of included text in a case
like this? Use one description of argument X, using FrameMaker
variables where C calls it by one name and COM calls it by another.
Import that description as a block of text into each version of
the document. Make changes to the text block, and have all four
versions updated with one stroke.

This could involve tools like fmbatch or dzbatcher
(see to do all the assembly.

Any experiences (good or bad) to share?

--Guy K. Haas
Senior Technical Writer
Selectica, Inc.
E-Mail: ghaas -at- selectica -dot- com

Previous by Author: Re: Bilingualism in TW
Next by Author: Re: (OT?) copyright and the web
Previous by Thread: SmartPDF from Coptech
Next by Thread: Consistent Terminology AND Single Sourcing AND Tools

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

Sponsored Ads