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

[Keith Hood <klhra -at- yahoo -dot- com>]

Only if the instructions actually are inconsistent and confusing. 

I was referring to wordings of lesser importance, such as describing how a new window appears on screen. It doesn't really matter, either from a technical view or a liability view, whether you write that a window opens, drops down, pops up, appears, displays, or flashes into being. That does not introduce confusion into what the user is supposed to do. (Although that last one may make the reader wonder what the writer was smoking.)

It matters a very great deal that you are consistent in the way you write about actions that the user must take. Visual aspects should be referred to uniformly - the button that is clicked to close a window should always be called the same thing. If the same function is available on several menus, that function should be described uniformly. Those things can affect which action a user takes next. If the same wording is always used for those things, it is more likely the user can quickly understand what to do next.

If an input field requires a particular kind of data, descriptions of that input must always give the user the same information about what is required. But even there, a little variety is not necessarily dangerous. 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.

I think writing about actions should be uniform if only to speed up the process. But descriptions are just that - descriptive. They can show some variations with no loss of usability or efficiency of information transfer.



--- On Fri, 6/6/08, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:

> From: Gene Kim-Eng <techwr -at- genek -dot- com>
> Subject: Re: Variety in Tech Writing (was: Display, Displays, or Appears)
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Date: Friday, June 6, 2008, 12:24 PM
> Product liability lawyers love documents like this.  Every
> new variation on the same intended meaning is another
> tasty ingredient in the recipe for a lawsuit based on
> inconsistent and confusing user instructions.
> 



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

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.