Re: Work around.....

[David John <David -at- BMIS -dot- DEMON -dot- CO -dot- UK>]

Hi Eric,

At 02:19 PM 12/20/98 -0700, you wrote:
>David,
>I think we fundamentally disagree about the purpose and function of a
technical communicator.
It looks like we do disagree.
>But if an expression is widely accepted in the target audience, >you'd
better have a darn good reason not to use it.
I have a slightly different take on this: if an expression is used in
source material, I'd better have a darn good reason for wanting to change
it.  And I trust myself enough now to be able to recognise a good candidate
for change, and also to be able to accept good reasons for leaving it be.
The responsibility lies on both sides, surely.
>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).
I don't know about that.  See the point I make later about 'learners'.
>- causes cognitive dissonance in readers who expect to see,  for example,
"this function returns ..." and see only
> "this function hauls off and fetches..."
It wasn't me that had a problem with 'returns'.  I think if anyone tried to
get round using the expression 'this function returns...', that would just
betray a lack of understanding of the programming domain.  The expression
is legitimate, proper, and (almost) *required* not because it is widely
accepted, but because that is what a function does (as somebody else
explained in a recent post), and there is no other way to say it.
>However, a good technical communicator can accommodate the
>style and vocabulary of the target audience without compromising
>good style and writing.
OK.
>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.
I wasn't quarrelling with the use of 'returns'.  I would find it odd if a
style guide tried to offer an alternative.  'Returns' has a legitimacy that
'workaround' does not.
> If the people who pay our salaries don't agree with that, our problems
range far deeper than word choice.
I'm afraid that they often don't agree with that; and, yes, our problems
range far wider than word choice.  My point exactly.
One of the most unpleasant professional experiences I ever had was to
discover that I'd been hired ostensibly to produce a user guide for a
product, only to discover that what 'they' really wanted was a document
that would complete the product package, and make it meet the requirements
of an industry regulator.  My focus was:
how do I tell my audience what they need to know?  Their focus was: does
this book cover what the regulators will expect to see covered?
>>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.
I remember taking great care in writing the last quoted sentence, but it
still missed the mark.  Ah well, c'est la vie.
May I draw attention to the word 'just' in that sentence?  Calling a spade
a spade is one of the first duties; it's not the last.
By the way, Eric: if I came across a bunch of people gathered round a
shovel and they were discussing it as if it were a spade, I'd get out of
there quick (yes, there is a difference).  In a less dramatic vein, when I
come across programmers who talk about dialog boxes by referring to them as
'windows' I try to get them to agree to stick to the correct terminology.
They usually agree.  My reason is that it avoids consistency problems;
their reason is that they just want me to go away quickly and leave them
alone...
>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?
One of the reasons why someone in the target audience may give up after the
first sentence is that the concepts (not just the language) are new.  I try
always to remember that part of the audience I'm addressing is the person
who doesn't already know what I'm talking about: the competent programmer
who is conversant with the terminology in one language or product but is
now learning about the area I'm writing about.  In that case what they
would like (in some types of manual only, of course) is for the concepts to
be 'unpacked' in simple language whose currency doesn't just come from the
fact that it is widely accepted.  There are of course various ways of doing
this: glossaries, explanations in text, etc...  But I consider it must be
done.   Certainly what they don't want is for me to make assumptions about
how hip they are to the current terminology.   (Is that what the 'educating
the user' thread in this forum was partly about?)  This person needs
special treatment, and I don't feel happy about making blanket assumptions
about widely accepted terms.
By the way, I presume, you felt OK about using the verb 'to grok' because
you assumed it is widely accepted and understood.  I don't know that word,
and I doubt whether many English speakers in the UK do (again, I'm trying
to  choose my words carefully).  While I accept that an e-mail post is not
a formal document, I think in a small way the inclusion of this piece of
localised language illustrates one of my points.
>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.
There are many reasons why I can't agree with that.  One reason is my own
taste, I suppose.  But I do also think it makes sense to try to keep
emotionally charged words out of formal documentation.  Some organisations
I have worked for claim to have evidence that words such as 'kill' and
'illegal' can carry unwanted emotional connotations, and I can well believe
it.
Also, style guides are there not just for 'my needs'.  Sure, I can choose
to disregard them wholesale and in particular things that they recommend.
But my understanding about style guides is that they are put together by
organisations in an attempt to constrain me to do things their way (thus
protecting their interests) sometimes in contrast to the way I might want
to do them.
>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."
IF you are arguing in favour of the pragmatism of the group, consider this
little story.
An acquaintance of mine who is not a technical communicator (but is slowly
being influenced by my one-man word police force) works in a group where
individual members have to submit weekly reports for publication on an
intranet web site.
The web admin guy issued instructions about what should be included in
individual reports.  One of the items was the date and time of individual
events.  This acquaintance complained that the instruction relating to date
and time was not precise enough and requested a clearer set of
instructions.  Back came the response: "You are the only one making a fuss
about this; everyone else in the group understands what I mean.  Let's just
get on with it."
Well, in the ensuing days, people submitted their reports, and, sure
enough,  dates and times were appearing in all sorts of formats.  The group
leader then had to make sure that the web admin guy gave more precise
instructions that everybody had to follow, to avoid serious confusion, and
to avoid the impression that the web site was being maintained by people
who just didn't care.
Anyway, many thanks for your response.

Regards,
David.

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