Enter vs. Type

[David Oberstadt <daveo -at- VNET -dot- IBM -dot- COM>]

(See referenced note at the end of this message.)

This is a valid point. I always start from the assumption
that most people are not dimwits, but some are.

I've seen variations on the same thing over and over including:

    Type 'XXXXX' and press Enter.  (with and w/o quotes)
    Type XXXXX, then press Enter.
    After typing XXXXX, press Enter.
    Enter XXXXX.
    (yes, there are more.)

I think some IBM mainframes even have a difference
between Enter and ENTER, but I don't know what it is.

I have never heard of anybody who is profoundly distrubed
by any of these variations, although some work better than
others. However, while testing a product once, we found we
had to give explicit instructions *not* to press enter
until told to.

The product had a window with several fields that the
user had to first fill in with such things as parameters,
source files, destinations, etc. A couple of the testers
pressed enter after completing a field, which was the same
as clicking the old 'OK'. The thing blew up without all
the fields filled in.

Yes, it could have been programmed so it gave a sweet
message if the fields were not all complete:

     Complete all fields before pressing enter.

But that is beside the point. The instructions told
them to TYPE the data into the fields, TAB to the next
field, then press Enter when it was all filled out.
Yet, we  s t i l l  had to tell them not to press
Enter or they will be sorry.

Everything has risks and you cannot (must not, even)
pick and pick at your documentation to make sure you
cover every single possibility of somebody misunder-
standing you. You see, somebody always misunderstands.

We do not have laws to cover everything a person might
do in every given situation. If a case comes up where
the law is unclear, the judge asks,"Did the defendant
act the way a reasonable person would act?" I like to
write documentation by the same standard. I ask,"Is this
documentation a reasonable person can follow?" Of course,
I have to think about who a 'reasonable person' is by
careful audience analysis and all that.


If you have read this far...
   I am intersted to find out what all you on the
   list read in your own time, if you're willing to
   share it. I believe good writers must be good
   readers as well.

   What technical publications or trade journals
   do you read? (I am not looking for suggestions!
   I am just interested in what you read. Thanks.)
   How many hours a week do you read?

   I keep to non-fiction--usually the local newspaper,
   history books, and sometimes some technical stuff.
   I estimate I read 10 hours a week. Probably more.


David Oberstadt               Santa Teresa Lab
daveo -at- vnet -dot- ibm -dot- com            San Jose, California


------------------------------- Referenced Note ---------------------------
From:     Judith Grobe Sachs <judygs -at- UIC -dot- EDU>

In his instructions he says to "type" commands.  It is my
contention that simply typing a command will not get you anywhere
-- you have to type it *and* press Enter.  So, in all the
documentation I write, I always "enter" commands (or type blah then
press Enter), and I try to make sure it's done that way in all the
documentation we produce.  (I'm the whole of the one whole and two
half people in documentation at the academic Computer Center at the
University of Illinois at Chicago.  We do a little bit of
everything, but mainly short "how to get started and where to go
for more information" type of documents.)  Some people around here
think this I go overboard a bit on this, but I know if we're not
careful, someone out there will simply type the command and wait
and wait and wait...  What do you all think?