Tuesday, April 28, 2009

Why do windows always display in my documentation?

According to several Technical Writers (TWers) on various e-mail lists, "display" is a transitive verb that requires an object. Not having an object is technically ungrammatical.
Well, this is one TWer that does not shy away from breaking a rule.
The following format is used in the documentation I write and maintain:
"Click Add. The [whatever] displays."
Grammatically, the above should be "The displays on your screen."
However, I object. There are two issues with this wording. First of all, in the context of documentation that describes PC-based software, "on your screen" is implied. Where else is it going to display? I think it invites the user to say "Where else is it going to display you moron." Secondly, I personally object to the word "screen." This is a tidbit I gleaned from my first Technical Writing "gig." My mentor at the time told me that your "screen" is a piece of hardware. What you see on your screen is a window. Therefore, in that light, I'd have to say "The "name of window" displays on your window" which is stupid. I admit I was very impressionable when I started Technical Writing and now consider myself very stubborn in the idiosyncrasies I've adopted.
I could take the easy way out and write "The XYZ window *appears*. That's as equally gross as using "on your screen." Using the word "appears" betrays the spirit of software, which is not magic. While I have no programming training, I have been a TWer since 2/10/95. I have learned "events" happen because the user inputs information or performs some action, which causes another action. In my macro coding, it is known as an "If-Then" macro. If the user press F9=Add, then the program will toggle to Add mode." It's very cause/effect. The word "appears"has a connotation of magic as in "I will make a rabbit appear in this hat. "Software is the anti-magician vocation. There is no magic. Nothing happens automagically.
Other ways to say this include "The ABC system displays the XYZ window." That one is so gross, I won't touch it.
So yes, while"display" is a transitive verb and yes, it does require an object, I don't see it as being an evil. Rather, it's a necessary evil.
When documenting PC-based software, I view "the "name of window" displays" as acceptable.

No comments: