Re: What is conditional text? (long reply)

[Chuck Melikian <chuckm -at- MDHOST -dot- CSE -dot- TEK -dot- COM>]

Someone wrote:

# Personally, I think conditional text, like automatically-generated HTML,
# is often a poor idea. If you can't be bothered to individually assemble
# the document, why assume that someone will want to individually read it?


I think he is right, sometimes conditional text is not a good idea. It
can be overdone which makes maintenance a chore at best. But, there are
cases where using conditional text is a significant time saver. Saying
"If you can't be bothered to individually assemble the document" flatly
ignores the effort required to implement conditional text and implies
that the writer is simply some lazy bozo that isn't serious enough about
the job to do it right. To put it kindly, these ideas are unwarranted
assumptions at best.

The purpose of conditional text is to save some time; if it doesn't
do that, don't use it. But, if you learn to use it well, it will save you
time.

I used a feature of Interleaf named Effectivity. This is Interleaf's
version of conditional text. One of the projects I have used conditonal
text was test equipment that is used to test fiber optic telephone transmission
lines. The standards (internationally defined) that define the operation
and protocols used in these transmission lines are known as SONET and SDH.
SONET originated in the US and SDH was derived from SONET but adapted to
better suit the systems outside the US, primarily in Europe. The two systems
operate almost identically. However, they use some different terminology
and they define some measures of performance differently. There are some
additional differences, but this post will be long as it is. :-)

The reason I mention all this is that the test sets we produce come in three
versions, a portable SONET version, a portable SDH version and a VXI version
that works with both SONET and SDH (VXI instruments are basically test
equipment on a card which is used in automated test systems). The user
interface is the same on both portable machines. Only the terminology used
in the interface is different. Though some physical connectors are different,
from six feet away, the portable test sets look virtually identical. The two
portable test sets operate identically. The programming commands for all three
test sets are the same.

I mention these things because, people that use SONET don't use SDH and those
that use SDH don't use SONET. So, writing a single manual to address both
customer audiences simply won't work.

What does this have to do with conditional text? We produced the equivalent
of 2300 pages of material for the manuals included with these instruments.
We wrote a user manual, programmer manual, and a service manual for each
of the portable test sets. We wrote a programmer manual, service manual and a
software user manual for the VXI version. By using conditional text
(Effectivity in Interleaf) we had to create only one book (set of files) to
produce the two portable test set user manuals (about 250 pages each), and
one book to create three Programmer manuals (about 300 pages each for the
portables and 660 pages for the VXI version). The Service manuals
are about 300 pages each and they also share files (for example, the
performance verification procedure) though not to the extent of the user
and programmer manuals.

The total number of printed pages for all the manuals that share files (that
is, use conditional text) is about 2300. However, because we used conditional
text, we really created about 1300 pages of unique material. We did this by
creating what can be thought of as variable components (components and inline
components to Interleaf users). These variable components are tagged
(attributes for Interleaf users) so that they only show up when the control
statement tells them to (that is, the control statement sets the condition).
We created variable components for each term that was different between SONET
and SDH. We created variables for each front-panel button or indicator light
that was different. We created variables for different artwork (screen
captures and illustrations).

The procedure for changing instrument settings is identical on both
portable instruments. The only difference is the name of the settings. Thus,
using conditional text we wrote procedures only once. That provides for
consistency. We have far fewer files to keep track of, which saves maintenance
time. And we only wrote about 300 pages of text rather than the equivalent
of 500 printed pages.

The files that describe the programming commands are actually used in three
printed manuals. We saved a lot of time writing because of the conditonal
text we used. The programming commands are identical for all three test
sets, but the variables (command argurments) are different depending on the
standard being addressed. For the most part, the command arguments are what
we wrote as conditional text.

Another example of how conditional text can save time is when a term is
changed. For example, originally there was a type of alarm named a Yellow
signal. Just before the product was to be released, the standards body
renamed the alarm to FERF (Far End Receive Failure). Because of our use
of conditional text, we went into one file (a Catalog for Interleaf users),
changed one entry (the item that defined the content of the variable component),
and the change rippled throughout the whole 2300 pages. No search and replace.
This change did delay our production by a few days (since the change occured
just the files were sent to print), but it was only few days not a few weeks.
Imagine how long it would have taken to open a couple of hundred files and
perform a manual search and replace!

Our use of conditional text on the project I've described was complicated
and involved. But, the alternative was to write two complete sets of
documentation for the portable test sets and create yet a third version
for the VXI test set. Granted, we could have just written one version
of the manuals for the SDH standard, copied the files and then modified the
copies to to work for SONET standard, but that still would have required more
time and would have led to inconsistencies, which we avoided by using
conditional text.

Using conditional text requires extra time. But when used appropriately,
it can save far more time than it costs and provide better documentation for
the user.

Chuck Melikian                                       chuck -dot- melikian -at- tek -dot- com

Worldwide Customer Communications
Measurement Business Division
Tektronix, Inc.

       *** I don't speak for them and they don't speak for me ***

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html