the magical appearance of dialog boxes

[mpriestley -at- VNET -dot- IBM -dot- COM]

Don writes:
>>>Write in the present tense, active voice, indicative mood.
>>>  "The system displays the dialog box"
>>>  not
>>>  "The dialog box appears"

I reply:
>>An unfortunate example.  I prefer the second to the first, and both are in th
>>present tense, active voice, and indicative mood (or has my grammar grown
>>completely rusty?).

Don replies:
>"The dialog box appears" is passive. Dialog boxes don't "appear" as
>though magical. The system or application displays them. I had this rule
>pounded into me by one of the best docos at this end of the galaxy, Hank
>Watters. Also a good boss. Granted, it's a purist's point of view, and as
>you can tell by a couple of sentences in this paragraph even us purists
>don't let it get in the way of our email.

>So your grammar may be a bit rusty, Michael, but considering for whom you
>work, that ain't bad.

>Watters made terrific roadkill gumbo, too.

As someone else has already pointed out, "appears" is indeed active (albeit
intransitive).  However, you're not the only person who feels it to be in
some sense magical (ie inappropriate).  You say the system displays them.
Someone else (sorry, I forget who) proposed that the user displays them.
I propose that sometimes the user displays them (by selecting a choice) and
sometimes the system displays them (spitting up a message out of the
mysterious (magical?) internal workings of the application).  Using the word
"appears" instead handles both kinds of situation.  I don't feel it is
magical, any more than the program "crashing" is magical, or a window closing.
Saying "the window appears" is short and clear.  About the only time I use
display instead is when directly describing the use of an "Open as" menu choice
(as in "Select Grundfindle to display the Grundfindle window").

Now, just to get huffy for a second, I'd say my grasp of grammar and usage is
actually fair-to-middlin', considering where I work.  There are a lot of
_extremely_ good technical writers here, who tear me to shreds regularly in
the internal techwriting forums (various ones for style, shoptalk, nitpicking,
etc.).  I'd be curious to know which IBM documentation gave you your opinion,
and I'd be surprised if it's more recent than 5 years old (which is an eon
in this industry!).  IBM has come a long way....

I'm enjoying the discussion, and I hope it continues.

Best of luck,

Michael Priestley
mpriestley -at- vnet -dot- ibm -dot- com
Information Developer
IBM Canada