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.
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.
