TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> > Can anybody provide an eloquent argument (maybe an
> > online article) for including definite articles in
> > procedures?
>>
>>Without article: "Remove lower bracket."
>>With article: "Remove the lower bracket."
>>I have argued that because the word "lower" can be a
>>verb or a noun depending on how it is used, the reader
>>must mentally insert the word "the" to make sense of
>>this sentence.
Bonnie Granat then proposed a founding principle :
...
>writing represents *speech.* It stands for speech. Writing
is
> not code, or shorthand, or a test of one's ingenuity. It
is a
> substitute for human speech.
A competing view is that writing serves as memory. This
doesn't really compete if you believe (as I do) that speech
is more like reading than writing. But in any case, paper
is the ultimate floppy, or the individual person's long term
storage place for learning and sensory data . In tech
writing, we have a crucial but oft-neglected business asset
that is tellingly called "Institutional memory".
I've got a response based in audience analysis, so it is
probably right. I will be describing a small, demanding
segment of all documentation users for whom I've written
technical documentation. I never would have believed,
before I met these users, that anyone would be this brash in
deconstructing the rules of written English, and with
ultimatums: "Look, Ned. I don't have time to read all your
articles and prepositions. Leave 'em out or I'll have to
find a writer who will." Simply breathtaking. I first
encountered this in a medical manufacturing company. My
lead recruited a licensed professional operator to review
the Operator Manual. The manual was a comprehensive
training manual for operators at hospitals that bought the
machine. The markup I got back had most prepositions and
articles lined out. Every sentence was edited down to
essentials. The word count was reduced 25% or more. See a
page from a similar draft (not marked up yet), and imagine
your most severe editorial slashing (lots of articles to
evict) to reduce word count and eliminate waffling. It's
OK, this manual was the one before we figured out what the
audience wanted. They never would have told us, BTW, if the
lead had not gone out to find reviewers from the audience:
Who are these users? They're highly-trained professionals,
usually, although they're anywhere that expertise
accumulates, who can cope with the vagaries of
"telegraphic-style" instructions. They can cope because
they know their job and the class of machines they use--any
such machine would have similar features and even a similar
user interface with pictogram-labeled keys. The users
become familar with it quicky.
Focussed reading is a foreground activity. These users are
trying to multitask, and can do so as long as tasks are
streamlined. They don't need to parse the information or
synthesize an appropriate mental model, they've got all that
stuff already. They only need documentation that refers
them, like a gesture, to the right mental model, which they
already know and understand. They want a few key words,
just enough to jar the memory loose from their long-term
storage memory, and dump it into working memory. They've
asked for procedures in the telegraphic style. That's a
style developed for sending simple, evocative messages that
convey some (not much) meaning. The recipient supplies all
the context and can reliably deduce the meaning without
foregrounding the whole information transfer.
Don't forget that printed words are recognizable as shapes,
even. No need to enagage in reading when a glance will do.
Grammar amounts to a formality, apparently, for this
audience. A common example is the visual spellers--you'll
hear them say things like "That word is misspelled. It
doesn't llook right. The telegram barely resembles
sentences: "Arriving by car 10 P 4/30. STOP Meet for late
dinner?" STOP Telegraphic style was economical--Western
Union today still charges per word. Leave out the fluffy
ones, save a quarter.
What this portends for the value of definite articles in
procedures is simple. You must include them for all users,
unless they don't want you to do it.
Happy Saturday Night, you Monday readers ;-).
Ned Bedinger
Edwordsmith Technical Communications Co.
doc -at- edwordsmith -dot- com http://www.edwordsmith.com
tel: 360-434-7197
fax: 360-769-7059
ROBOHELP X5 - ALL NEW VERSION. Now with Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more!
Now is the best time to buy - special end of month promos, including:
$100 mail-in rebate; Free online orientation on content management
functionality; Huge savings on support and future product releases;
PLUS Great discounts on RoboHelp training. OFFER EXPIRES April 30th!
Call 1-800-358-9370 or visit: http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
