Re: Work around.....

["Eric J. Ray" <ejray -at- RAYCOMM -dot- COM>]

David,
I think we fundamentally disagree about the purpose and
function of a technical communicator. I don't generally
like rebutting messages point by point, but am making a
bit of an exception here.

>writing that we are entitled to use potentially unfamiliar terms without
>explaining them first.  You, on the other hand, wish to persuade me that I
>must use such terms, even if I suspect they are potentially problematical,
>on the grounds that they are widely accepted.  I think you will readily
>agree that because an expression is widely accepted, does not mean that we
>have to use it.

But if an expression is widely accepted in the target audience,
you'd better have a darn good reason not to use it. By definition,
if a term is widely accepted in the target audience, it's not
potentially problematical (at least no more so than anything
else in language).

>but what if at least one language element in that  manual:
>
>- violates some legal or stylistic requirement that the organisation is
>striving to observe
>- inadvertently presents some negative aspect of the feature or process
>described
>- poses a momentary comprehension problem for readers whose mother tongue
>is not the brand of English spoken in your locality
>- puts a rival product in a bad light
>- somehow just strikes the wrong tone
>etc...

This is the same set of potential difficulties that _ANY_ document
presents. However, if we put on a "Trustee of the Language" hat
and attempt to use substitutes for "returns" in the programming
sense or euphemisms for "workaround" in general, then we add
more items to your list. Specifically, we add
- inadvertently confuses members of the target audience who
        assume that because you use an unexpected term that
        you also intend a different meaning.
- causes cognitive dissonance in readers who expect to see,
        for example, "this function returns ..." and see only
        "this function hauls off and fetches..."

However, a good technical communicator can accommodate the
style and vocabulary of the target audience without compromising
good style and writing.

>And, do we not take steps to prevent the manual being, er, *badly written*
>though it pays lip service to language that is understood by its audience?
> By badly written I mean: no structure, inaccurate or missing information,
>poorly indexed.   (See Footnote 1).

But absolutely, and I don't think that anyone suggested otherwise.
IMHO, structure and organization are far more important than
haggling over terminology, and appropriately selected content
is essential.

>Shouldn't we be concerned about slang, jargon, some widely accepted
>terminology?  Isn't that why we have style guides (See Footnote 3) and word
>lists and editors desks and legal editors and approval processes, and so
>on?   Isn't that why we get our scribblings reviewed and approved not just
>by developers and model users, but also by their managers and our managers?

Ummmm, nope. If I have a style guide that tells me to use
some hack of a workaround for "This function returns..." for
an audience of programmers, I need a new style guide,
documented exceptions to the current one, or some other
alternative.

Technical writers--at least this one--are paid to communicate,
and not to attempt in vain to protect the language.
We should be concerned about communicating effectively
to our target audience. Period. If the people who pay
our salaries don't agree with that, our problems range far
deeper than word choice.

>reason or another.  However, in my view, documentation would be a lot worse
>if writers and the organisations they work for did not (as I think they do
>currently - at least the ones I know)  fuss over the wider considerations
>I'm talking about.   It's most definitely not just about calling a spade a
>spade.

But it _IS_ about calling a spade a spade. Or, if your audience
commonly calls it a Leaning Highway Worker Support Device, you call it
that. Or maybe it's technically a spade, but everyone calls it
a shovel. That's what you do. You can add alternative terminology,
but don't force the "right" term if you have one that will
be widely and accurately understood.

>I'm not sure myself about this one, but it occurs to me to ask it anyway:
>What if we end up with a programmer's guide that  is understandable *only*
>by programmers?  Do we say 'that's OK, because it's intended only for
>program,mers'.  Hmmm!

I'm not sure about your choice of "understandable", but if I write
a programmers guide for programmers, I'm only concerned about
how usable it is for them. If others can grok it, great, but if
it's thoroughly usable and effective for the target audience and
nobody else can even wade through the first sentence, so what?

>Footnote 3
>Have you thrown your style guides out the window yet?  You know, the ones
>that say things like:
>X nonrecoverable [adj]. Use 'irrecoverable'...
>X illegal [adj]. Do not use. Use 'not allowed'...

Only the ones that don't meet my needs. For example, the
examples you cite here would be fine for a style guide used
for an end-user audience, but I'd not be using this style
guide for an audience of programmers. Circumlocutions
like "not allowed" for "illegal", when the audience expects
illegal, don't facilitate effective communication.

>I find I need this kind of advice all the time, to stop me saying in
>manuals the very kinds of thing programmers say amongst themselves.

Why would you want to do that? Your sentence sound to me like
"I find I need this kind of advice all the time, to stop me from
communicating effectively, while using the terms, phrases, and
jargon that my target audience does."

Eric
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Eric J. Ray    RayComm, Inc.
http://www.raycomm.com/      ejray -at- raycomm -dot- com

*Award-winning author of several popular computer books
*Syndicated columnist: Rays on Computing
*Technology Department Editor, _Technical Communication_


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=