Monday, June 27, 2016

Why do windows always display in documentation?

I dug up this essay from 11 years ago and lightly edited it.
The word "display" is a transitive verb that requires an object. Not having an object is technically ungrammatical. I do not shy away from breaking a rule.
The following format is used in the documentation I maintain:
"Click Add. The [Name of the Window] displays."
Grammatically, it should be "The [Name of the Window] displays on your screen."
However, I object. I have 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 the 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, over 20 years in software documentation has taught me that "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 automatically.
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 the Window] displays" as acceptable.

No comments: