Basic Voice ??s: OK for Software to "allow", "let", "enable", "pr ovide" and so forth?

Subject: Basic Voice ??s: OK for Software to "allow", "let", "enable", "pr ovide" and so forth?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 11 Feb 2003 11:56:49 -0500


Peter Swisher reports: <<It seems that every descriptive sentence I write
goes something like this: The software "enables" you to, The software has
functionality that "lets" you, Screen XXX "provides"... What other verbage
choices do I have?>>

This approach is fine if you're marketing the product, but in documentation,
the reader doesn't need this kind of sales pitch: they already (mostly) know
what they'll be allowed (let) to do, and just want to know how to do it. To
facilitate skimming, begin the introductory paragraph with a heading (e.g.,
"Doing X"); begin the first paragraph under the heading with "To do X...",
then jump right into the instructions.

If you have several "to do" sections in one topic, start the topic with
"This [help topic or section] explains the following tasks: Doing X, Faking
Y, and Emulating Z". Each of these tasks should be indented beneath the
introductory topic, and linked to the relevant section of the overall topic.
That section should, of course, have a matching heading.

Modify as necessary for different contexts.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.



Previous by Author: Technical writing tests?
Next by Author: Basic Voice ??s: OK for Software to "allow", "let", "enable", "pr ovide" and so forth?
Previous by Thread: Re: Basic Voice ??s: OK for Software to "allow", "let", "enable", "provide" and so forth?
Next by Thread: Basic Voice ??s: OK for Software to "allow", "let", "enable", "pr ovide" and so forth?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads