Basic rules of technical writing: A summary?

[CJBenz <cjbenz -at- AOL -dot- COM>]

There's just no way for me to respond to all the posts and direct messages
I've received regarding my original and subsequent posts on this
issue--and still find time to eat and sleep. Please accept this as a
substitute for various individual responses.

For the benefit of reference, here are the rules I originally suggested:
1. Make it understandable.
2. Make it consistent, unless that interferes with Rule 1.
3. Make it grammatically correct, unless that interferes with Rule 1 or 2.
4. Make it technically correct, unless that interferes with Rule 1, 2, or
3. (Or, in a later version, make it technically correct.)

Some observations:

1) I found it interesting that so many people attacked my ranking levels.
Many insisted that #4 be #1, etc. The most common criticism was along the
lines of "What? It's OK if you very understandably lie to someone?"

Although I'm sure we could argue forever about the ranking of these four
rules, I now hold forth that there can be no sense to an absolute ranking
to critical writing elements. For example, many detractors insisted that
technical correctness rank above understandability. However, I prefer the
middle ground promoted by some moderates of striking a balance between
understandability and correctness. Can understandability and technical
correctness be ranked one above the other? Are they not together the *sine
qua non* of technical writing? Is there purpose in one without the other?

2) Some people wondered what I meant by "technical correctness." For
example, did it imply accuracy, completeness, or what? My short answer:
"It depends."

Although accuracy is generally an admirable goal, this is not always the
case. The English language's wide selection of euphemisms serves as
evidence of the needs and desires to purposely *avoid* accuracy. True
accuracy is rarely appreciated, for example, when dining on a meal of
escargot, tripe, and head cheese.

Completeness can also be problematic. When your 5-year-old asks you where
babies come from, do you really think you should tell her the complete
story? My feelings go out to technical writers who bear the constant
pressure to document every last facet of every last element of every last
feature. If you have a good solution to this, I'd love to hear it.

My idea of technical correctness, then, is delivering just as much of the
truth as necessary, in a manner that readers can understand and easily
accept. In a beginner-level book, for example, it would be more or less
technically correct to say "You computer monitor is just like a TV
screen." The same statement in a document for computer engineers could be
ludicrous. As someone in this thread quoted earlier from Elements of
Style, "Know thy audience." How exactly we go about knowing this audience,
of course, is a complex matter worthy of an entirely new thread.

3) Although I thought I had a good understanding of personal communication
dynamics, it's amazing to learn once again how different online
discussions are from face-to-face ones. I am the type of person who likes
to throw out an 80%-completed idea as if it were 100% complete, and then
see if and how other people knock holes through it. (I read somewhere that
if you want to get a rapid online response, don't ask a question, just
post the wrong answer.) In a face-to-face setting, I generally get a
dramatically improved idea in a matter of minutes with little or no
effort. Trying the same thing online, though, results in a torrent of
responses from a variety of directions, all demanding individual responses
in their own way. Consensus is difficult to achieve, and cross-support is
virtually nonexistent. On the positive side, everyone gets a chance to
submit their own ideas independently, without fear of being drowned out in
the argument.

I'll bet there's a book or at least a paper in this somewhere. Does
anybody have that information on submitting STC proposals? <g>

4) My many thanks to everyone who participated (and no doubt will continue
to participate) in this thread. I'm glad to know that I'm not the only
writer out there who struggles with priorities in writing, especially in
an industry where we often have to sensibly document the nonsensical.

For now, though, I'm bowing out. I need to catch up on some of those other
threads out there...


Chris Benz
Author, Technical Writer, Computer Trainer
6229438 -at- mcimail -dot- com
"You learn something new every day--whether you want to or not."