RE: Displays versus Appears-Which One?

["Michael West" <mike -dot- west -at- oz -dot- quest -dot- com>]

Somebody wrote:

> I also don't like 'appear' for this very reason. This would indicate
> that the box did not exist previously in any way and was only now
> created magically. 

The idea that the verb "appears" has
something to do with magic has been
voiced here before. There is nothing whatever
in the ordinary usage of "appears" that
justifies this assertion.

An illustration appears on page 12 of
my document. A ship appears on the
horizon. A man appears on TV. A letter 
appears in my mailbox. My cat appeared
at the kitchen window. And yes, a dialog
appears on the screen when I click something. 

There is nothing "magical" implied.

"Displays" without an object, on the other
hand, is ungrammatical according to most
standard usage guides--though it is never
hard to find inexperienced writers who think
they're way too clever to use those stuffy
old rulebooks.

I also agree with a number of structured writing
experts who suggest that statements like
"a window opens" (or whatever) have no
place in a list of instructions. Why? Because
they are not instructions and they lack user
focus. Why would we point out that something
"appears" unless we want the user to understand 
that there is a REASON for it -- a USE for it?
"The xyz dialog appears" is a descriptive
statement. It describes the behavior of
the software. But is that the purpose of the
user guide? Is that what the user is mainly
interested in?

Not usually. The user is interested
in knowing what the USER must do to get a 
desired result. At least, that's what * I * want
to know when I read a user guide. What dialogs
"appear" is only interesting insofar as they enable
me to accomplish something. The fact that something
"appears" is fairly useless without some indication of
why it is significant. 

So instead of merely describing it as if it was
a meaningless event, let's focus on its utility.
And here's the really neat thing. With a 
little thought, you can make these useless
descriptive statements into usable instructions. 
For example:

1. Click abc.
2. In the xyz dialog, select a blooper.

There is no reason that I can think of to
insert "The xyz dialog appears" before the
second instruction.

This is another instance where it is
important to remember the purpose of
the document and the needs of the
audience.

I might be persuaded to make an exception if writing
for novice computer users who might be startled half 
out of their wits by something appearing on the screen 
without prior warning--not that mentioning it in the
instructions is necessarily going to help them deal
with this mysterious phenomenon.



-- 
Michael West
Technical Writer
Melbourne, Australia



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
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.