Re: GNOME Documentation Style Guide

["Eugene O'Connor" <eugene oconnor sun com>]

Thanks for taking the time to review and comment on the style guide and
wordlist. We considered many of the points you raised during the heated
discussions of our documentation team, and I have detailed why we chose
what we chose below.

"Rebecca J. Walter" wrote:
> 
> Questions:
> regarding apostrophes... If not for possessives, are we supposed to use
> of for all possessives or write them wrong?

We are not suggesting to write the possessive "s" without the
apostrophe. Our intention is to use a construction such as "the x of the
y" rather than "the y's x". 

Many people do not have a clear understanding of the correct usage of
the apostrophe. This is true not just for non-native English speakers,
but also for native English speakers. There may be confusion with the
use of the apostrophe for a contraction ("don't"). 

The "of the" construction is simpler and clearer, and we believe makes
the documentation more usable for native and non-native English speakers
alike. It also provides a side benefit in reducing translation costs.

> 
> deselect is not a word. i strongly object to use of it when unselect is
> grammatically correct.

Neither deselect nor unselect are listed in the American Heritage
Dictionary. These terms are not established long enough to be included
in a volume such as the AHD. However, the industry that we work in often
coins new terms, and we need to be open to using such terms, for our
documentation to meet the expectations of our users.

Deselect is one such new term. The de- prefix is more often used with
verbs, and the un- prefix is more often used with adjectives, adverbs,
and nouns. The de- prefix can mean "to do the opposite of" and "to
remove from". So deselect means the opposite of select and to remove the
selection from an item. I do not get the same sense of "to remove from"
from the un- prefix.

Perhaps this is a subjective opinion, and perhaps the best way to
resolve this question is to perform usability testing on documentation
that uses these terms.

But the most basic test that our terms need to pass is: Is the meaning
clear? I believe that the meaning of deselect is clear. 

> 
> e-mail is correct.  email is not.

The history of new terms shows that as the term gains popularity,
devices that mark the term as new, such as hyphenation, or
capitalization are dropped. This is particularly true of technological
terms, for example laser and radar. 

A search on Altavista for "email" returns about 77 million hits. A
search for "e-mail" returns about 16 million hits. This suggests that
dropping the hyphen is acceptable at this point. 

The Compact American Dictionary of Computer Words gives email first,
then e-mail, and also E-mail.

> 
> return vs. enter.  new keyboards do not have a return key.  users
> inexperienced with old keyboards will be unable to find the "return"
> key.  many new keyboards use only the symbol of the arrow pointing left
> with a vertical extension on the right side.

There are three reasons why we chose to call this key Return rather than
Enter.

First, we do not want to use the term Enter key for both the Return key
and the Enter key as in may cases these keys do not do the same thing.
For example, in gedit I cannot add a new line by pressing Enter. In
GNOME Calculator, I cannot calculate a sum by pressing Return.

Second, we use the verb enter to mean inputting data to a text box, and
want to avoid any possible confusion or ambiguity.

Third, the keyboards that we use all have Return written on the Return
key. It is only on PC keyboards that I have seen the arrow that you
describe with no accompanying text.

> 
> plugin: all old gnome stuff and all netscape stuff uses plug-in.  why
> the switch?

We chose plugin without the hyphen for the following reasons:

First, given the currency of this term, we felt it was acceptable to
drop the hyphen. A search on Altavista for "plugin" returns about half a
million hits. A search for "plug-in" returns about quarter of a million
hits. This indicates that dropping the hyphen is acceptable at this
point. 

Second, plugin appears in several places on the GNOME UI. For example,
gedit, GIMP, and Dia. Netscape Communicator 4.7 uses "plug in" as a noun
as two unhyphenated words, so perhaps we should not necessarily take our
lead from that.