Re: Work around.....

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

>David John replied to Toni Lee McCreash:
>>
>>>... "work-around", "work around", or "workaround". Can someone tell
>>>me which is correct? Thank you.
>>>
>>It's not in any dictionary probably because it's really (undesirable)
>>jargon masquerading as a word.  One way to get round your problem is not to
>>attempt to use it at all, like I've just done!
>

Susan W. Gallagher replied:
>Sorry, David. Your workaround just doesn't cut it. "Workaround" has
>become standard terminology and to call it something else just hides
>the information from the user. Even if you manage to avoid it in the
>text (although I'm wondering why you would want to), you most certainly
>need to include it in the index so that those users who -- if you will
>excuse the expression -- call a spade a spade will be able to locate
>the information quickly without having to guess at what you've called
>it. Personally, I'd include "workaround" in the section title so it'd
>appear in the toc too.
>
>Our mission is to convey information as quickly and clearly as we can.
>To do that, we need to use the vocabulary of our users and "workaround"
>is definitely part of that vocabulary.
>
>

Oh, dear.  It looks like I've been suckered into delivering one of my
lectures again.  Sorry this is rather long, but I think there's  food for
thought here.

< "Workaround" has become standard terminology and to call it something
else just hides the information from the user. >

Ah, 'standard terminology'!  There have been a number of posts recently on
this very topic.  In my opinion, we technical writers ('technical
communicators', or whatever) have a duty to use language and methods
appropriate for the target audience and also the PURPOSE AND TONE of
whatever we are producing.  The notion of a  'standard terminology' does
little to help in this respect.

I'm entirely in favour of being familiar with the terminology of our target
audiences.  This is essential for understanding the people you are talking
to, and also for understanding the material supplied by subject matter
experts ('information sources' as we call them over here), but it's not as
simple as 'we can or even *should* use this or that word or expression
because they use it and understand it'.

I maintain that what we do most of the time (whatever the target audiences)
 is formal writing.  Let's not confuse 'easy-to-understand' with 'informal'
or 'familiar' or 'slack'.  Often what we have to do is to take informally
given information and produce documents and other materials that carry
authority and that are clear.  Being authoritative means avoiding doubt or
anxiety or inconsistency;  being clear means avoiding confusion (that's why
we do spell-checking and editing and other stuff like that).  One of the
ways we can needlessly introduce confusion is by using language that may be
doubtful, when there are plainer alternatives.

For example, most of the documents I've worked on in my writing career to
date have been for software developers.  In that domain, I can think of a
whole number of expressions that developers use that you just wouldn't want
to appear in formal writing.  And I'm not thinking of anything particularly
crude here.  I mean things like the following: software developers very
often talk about features or behaviours being 'hard-wired' (hardwired?),
and we know  what they mean; but I would want to avoid using the term,
simply because it can be confusing; and even if the confusion lasts but a
fleeting moment, that's something I think I ought to spare my readers.

Further, consider this: even when you think that your audience is very
restricted, there is always the need to cater for users whose mother tongue
is not English, or American English.  I'm sure that plain language that as
far as possible avoids doubtful elements is to be preferred, for the sake
of such users.

Oh, and whether an expression is in a dictionary or not has no influence on
its appropriateness for a given audience or document.

<Even if you manage to avoid it in the text (although I'm wondering why you
would want to),>

Because whenever there is doubt in my mind about a word or expression (for
example, its spelling, or its plural form), one of my first instincts is to
consider using a plainer form of words.  This is especially true when the
doubtful expressions have no 'technical' basis; by which I mean, for
example: in a user guide for a software development methodology product,
the term 'work-around' does not have any technical basis, but the term
'desgn pattern'  has.

The eagle-eyed will notice that even while preparing this note I've had
difficulty maintaining consistency over my spelling of the word(s) in
question: is it 'work-around', 'workaround', 'work around', etc?   Frankly,
I can't be bothered.  Besides, the difficulty illustrates my point well...

<you most certainly need to include it in the index so that those users who
-- if you will excuse the expression -- call a spade a spade will be able
to locate the information quickly without having to guess at what you've
called
it. Personally, I'd include "workaround" in the section title so it'd
appear in the toc too.>

Well, this is the bit that worries me most.  If I understand you right, you
are saying that I shouldn't just be avoiding the use of what I consider to
be a suspect expression, but I have a duty to use it, and to draw attention
to it as well!  This is unacceptable counsel, especially as regards this
particular expression: 'work-around'  (or workaround, or whatever).  As I
understand it,  a work-around  is a suggested fix for a regrettable
temporary defect in a process or a product.  It's something you
apologetically tell users about in a readme file or by word of mouth, or
through field support people.  You don't shout it from the rooftops,
publish it as if that's part of why you're in business.

In my view, the discipline required here is this:  if I'm describing how to
do something, I present the process.  If I'm describing a product, I
present its features and its capabilities.  That's it.  I index the
processes and I index the features.  My topic headings mention the
processes and the features. I'm not going to go out of my way to tell about
temporary defects, because THAT DESTROYS CONFIDENCE.

<Our mission is to convey information as quickly and clearly as we can.  To
do that, we need to use the vocabulary of our users and "workaround" is
definitely part of that vocabulary.>

No, we don't need to use the vocabulary of our users to do that.  We need
to use our judgement about appropriate language and terminology.  The main
reason for getting familiar with the language of our users is to be able to
understand the problem domain; we don't have to repeat what they say in the
way they say it.  We are in the business of transforming more or less raw,
unusable information, and the transformation has many aspects, in which we
are the experts.  Remember, that's supposed to be why they hired us.  If we
are unwilling or unable to provide this added value, then perhaps we ought
to leave technical communication to the people who like to call a spade a
spade, and then where would we be?
Cheers,
David.

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