Re: Word Choice

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

Mike Christie wonders about choosing to use more words for accuracy:

> I was re-writing a programmer's document to include in the user manual.
> He used the word "expensive" to indicate that that a procedure used a lot
> of system resources.

[...]

> The question, of course, is, are there times when more words are better
> than fewer? Should one >>always<< avoid colloqualisms, even when the target
> audience will certainly understand what is meant? Should one always err
> on the side of accuracy even when it means using more words?

Good question. One person's jargon is another person's terminology. And
there seems to be a fine line dividing the two.

I'm not sure in this case that "expensive" is a colloquialism. I admit
that even though I co-authored an entire book on efficient programming
practices, I don't think I ever used "expensive", but now that I see it
in this context, I probably *would* use it if writing that book again.

In response to the larger question about >>always<< avoiding
colloquialisms, the answer is "it depends on your audience". I would
avoid jargon as much as possible for an audience with a composition
spanning the full range of experience with a product/language/piece of
equipment/ etc. For an internal document aimed at experts, I'd loosen up
a little. And you *can* get away with coining terms to save words, if
you are pretty sure the term has no *other* industry equivalent.

Imagine trying to describe object-oriented analysis and design without
referring to OOPS jargon. Of course, it's not jargon anymore; it's
terminology. You would confuse members of your audience familiar with
the terminology, even though you might speak more clearly to those with
less experience. However, avoiding the jargon might contribute to your
readers' confusion when they read other books that *do* use the
terminology.

And it would be much worse to coin a whole bunch of *new* jargon words
to avoid using the old ones. Nothing is worse than proliferating jargon
when perfectly acceptable jargon already exists. 8-)

Generally, it's a judgement call whether a particular term is common
enough to use in technical documents. All other things being equal, I
always try to err on the side of less words. Sometimes I mess up, but
what can you do?

|Len Olszewski, Technical Writer |   "To err is human, but it feels   |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA|    divine." - Mae West             |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|