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.
A function is a process - when something goes in, something else comes
out. In that sense the process does something, just like your toaster
does. Now, you could say your toaster *lets* you toast your bread, but
that puts you in league with Zippy the Pinhead, cowtowing to and
worshipping your household appliances. (Don't knock it 'till you try
it...) You could also say that you *use* your toaster to toast your
bread, and this is also true - you might and may use other things to
toast your bread on other occasions.
But it's no less true to say that once you put the bread in the toaster
and push the lever down, the *toaster* actually toasts your bread. The
toaster doesn't need to be alive to do that. By your volition you have
handed your bread over to the toaster and are expecting certain results.
Once you'rve done that, I defy you to demonstrate that anything other
than the toaster is toasting your bread. (I suppose Superman could do
it without a toaster - heat vision and all that.)
In other words, when you use your toaster, the toaster toasts your bread.
This actually opens up some interesting considerations about prosthetics
and their boundaries of effect. When you have a prosthetic leg, do you
walk or does the leg walk? You do, of course. But that's because
walking or even standing is far more complicated than anything the
prosthetic is designed to do. However, when you lean on the leg, are
you supporting your weight, or is the prosthetic supporting it? I say
the prosthetic is supporting your weight - the issue is in defining the
limits of the prosthetic effect. In this case the prosthetic is
designed to support your weight, and that's what it does.
Now, the marketing dept will say this leg allows you to walk, and
they're more or less correct to say so. With this prosthesis you have
the capacity to overcome a specific obstacle - you can walk. But more
strictly, the prosthesis doesn't grant you permission, so you still have
to be careful about the nuance. And the prosthesis most certainly
doesn't allow you to put your weight on it. It simply supports your
weight. (Your insurance policy is what allows you to put your weight on
the prosthetic.) So if the marketeers want to get down to that level of
detail, they had better start talking to the tech writers and engineers
before they put their prosthetic feet in their mouths.
All this blather actually leads to a decent conclusion. A full
understand of the device you're describing leads you to criteria for
choice of active verb, passive verb, or conditionals such as allow, let,
might, may, and can. In other words, technical writing demands a
technical understanding of the subject. The job is to remove mystery -
as you do so the criteria for this type of decision become obvious. The
decisions you make determine how much mystery (or clarity and precision)
you transmit to your readers.
"<snip> but the function doesn't really "do" anything by itself, other
than just sit there. The user implements the function as a tool in order
to carry out his or her bidding (i.e., it allows him or her to save
changes)."=20
Aha! Herein lies the precise reason I find myself using "lets",
"allows", "provides" etc. Thanks for reminding me! The code is not
alive. It cannot do anything by itself. They say the first step to
recovery is identifying the problem.=20
"<snip> there's no reason to put "allows you to" in every single
description. Just clutters things up and states the obvious."
I'll repeat this to myself every morning. Eventually, it will sink in.
At the least, everybody's help has been fantastic. I'm over my little
"tech writer's block".=20
--
Chris Despopoulos, maker of CudSpan Freeware...
Plugins to Enhance FrameMaker & FrameMaker+SGML http://www.telecable.es/personales/cud/
cud -at- telecable -dot- es
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -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.