RE: Variety in Tech Writing (was: Display, Displays, or Appears)

["Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>]

Keith Hood wrote:

> Say you have a field where you enter a new password, and the password
has
> to include both letters and numbers. You could express that several
ways:
> 
>   "Use both letters and numbers in the new password."
>   "The password must have letter and numbers."
>   "Valid passwords will contain numbers and letters."
> 
> All these descriptions give the same information. If you have multiple
> places where the user has to create a new password (I've seen
applications
> like that), it doesn't hurt to use slightly different wording of how
the
> password must be structured, as long as the reader quickly and easily
> understands the main requirements.

Actually, it does hurt. In the third sentence, for instance, the change
to future tense and reversal of order to "numbers and letters" will
require me to slow down while my mind confirms that this requirement
really is the same as the one I learned earlier. 

It may not take long or be dangerous, but you've increased the cognitive
load. Multiply that by a thousand instances, and using your document
requires significantly more mental effort than it needs to. 

I rarely read software manuals in front of the fire in the evening. I
generally read them to perform a task or solve a problem. You don't need
to amuse me or even strive to avoid boring me. You just need to give me
the information I need in the most efficient, least burdensome way
possible. 

The variations you embrace don't benefit me, the reader, they benefit
you, the writer -- they keep _you_ from getting bored. Selfish bastard.
;-)

Richard


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------






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

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.