Display, Displays, or Appears?

Subject: Display, Displays, or Appears?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: techwr-l List <techwr-l -at- lists -dot- techwr-l -dot- com>, Tim Lewis <ltc -dot- writer -at- comcast -dot- net>
Date: Thu, 05 Jun 2008 14:47:38 -0400

Tim Lewis wonders: <<For software user guides, I prefer to not use
the word, "appear" or "appears" when the user clicks a button or
selects a menu choice and something shows up on the screen.>>

It's better to avoid all four words (appear, appears, display,
displays) so you can focus on the goal or the action rather than the
result. Where it's necessary or useful to start with the context, use
a form such as "To accomplish X, do Y". Alternatively, if the overall
context has been established already (e.g., by a heading such as
"Printing your document"), simply list the steps: "Do Y." Remember,
the reader's goal is to perform an intermediate action the leads them
to a larger goal, not to learn about things they can clearly see with
their own eyes.

Think of it this way: If there is only one result (e.g., displaying a
dialog box), describing that result is rarely useful: If the software
behaves the way it should, the result of the action is clear, and
telling the reader about what they just saw is redundant. If the
software fails to behave properly, describing what they should be
seeing -- but are not seeing -- is frustrating at best, and
intimidating or infuriating at worst. However, it's reasonable to
provide more context along the way. For example: "Open the File menu
and select Print. In the Print Dialog box, select..." That helps
clarify that the person shouldn't click a toolbar icon or select
another menu item, for example. Sometimes that clarity is necessary.

It's been argued that explaining the result is important so readers
will know what to expect. This is more true for situations in which
two or more behaviors are possible. For example: "If the light turns
green, open the door. If the light turns red, run for your life."

-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
***Now available*** _Effective onscreen editing_

Print version: http://stores.lulu.com/store.php?fStoreID=1505747


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.

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.


Previous by Author: Use of "Please" and the Like in Documentation?
Next by Author: Re: Display, Displays, or Appears? (take II)
Previous by Thread: Re: Display, Displays, or Appears
Next by Thread: Re: Display, Displays, or Appears?

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

Sponsored Ads