Naming Conventions

[John Bell <johnbell -at- MNSINC -dot- COM>]

You wrote:
> There has been a small debate in the office over how "screens" should be
> referenced in the documentation.  I'm curious as to what others call
> what I refer to as screens.  The debate includes calling them screens,
> dialogs, and windows.  What is the norm or proper term and are the three
> terms above the same?

I wrote a style guide earlier this year, and I addressed that same issue. Here
are two passages that deal with this problem.

Ambiguity
_________
The goal of technical writing is to write so that the reader cannot
possibly misunderstand you. You should avoid words that impart shades of
meaning. Strive to find the word that means exactly what you want to say.
Avoid words that are non-specific, misleading, or need further definition.
A prime example of an ambiguous word is "system". In software documentation
many writers use the phrase "the system" to mean their application
software. They will also use the phrase to mean the combination of the
computer, the operating software, and their application software. In some
documents you will even find the phrase "the system" to refer to the
combination of the printer, network, computer, operating software, and the
application software. The writer expects the reader to determine the
definition of "the system" from context. This is poor technical writing.
The chances of the reader misunderstanding the term are very high.
In the English language we normally use one word to have many meanings. The
American Heritage Dictionary lists 24 definitions of the word "screen",
including the few in this list.
The phosphorescent surface of a computer monitor
The image displayed on a monitor
To conceal from view
To examine (for example: data) in order to determine suitability
A reader of computer oriented literature must determine based on context
which of these four meanings the author intends. In such a situation you
must select one definition of the word and use it consistently throughout
the document. Chapter 4, "Word Usage", lists specific meanings for typical
words. Please send any additions to the word list to John Bell.


Now, from Chapter 4, "Word Usage"....

screen (n.)
Avoid. Use "screen" to refer to the graphic portion of the monitor. Use
"monitor" to refer to the television-like hardware that includes the
screen. Use "display" to refer to a visual output device like the
flat-panel on a laptop computer. Do not use "screen" to refer to a GUI
element, such as a window or dialog box. Avoid using "screen" by itself
because of possible confusion between television screens and computer
screens (monitors).


And now a more recent note....
The term "screen" became popular way back in the pre-GUI days of computerdom
because the displays in those days were character based, and were usually 80x25
in size. The entire contents of the display (or screen) would change when you
called up a new function. Calling an arrangement of 80x25 characters a screen
was a convenient term, and frankly it stuck because there is no suitable
phrase to use instead.

In the modern GUI age, what we see on our displays is a collage of windows.
I used to get persnickety and insist on calling things by their right names.
This is a window, its child is a dialog box, this other entity is a pop-up,
and so on. I have since relented. I discovered that using the precisely proper
terms made the text clumsy, and the readers didn't really care about the
subtle differences betweeb the entities. I now use the term "window" to refer
to all display entities generically. Only when I need to specify the differences
between a dialog, window, pop-up, and so on do I do so. I guarantee you that
few readers care that we use a modal vs. modeless dialog box for this or that
function. They quickly learn the differences in how modal vs. modeless dialogs
work, and how to recognize them in their software.

Enjoy!
--- John Bell
    johnbell -at- mnsinc -dot- com
    johnb -at- c-stone -dot- com

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-