word usage (e-mail vs email, log-in vs log in, add-on vs plug-in, performance, etc.)
dwx
For consistancy with (English) documentation, I think we need a style guide to
word choices and grammar. Below is just a short list of words that we should
watch out for. Feel free to add more entries. Also feel free to disagree with
me.
e-mail and email: n. electronic mail
Both variants are commonly accepted. The general public seems drop the hyphen
while editors (and probably English professors) seems to favor "e-mail". (I favor
"e-mail" because it retains the original meaning and because it's more readable.)
However, since "email" is used in mozilla more than "e-mail" is, the hyphen-ized
form should be used.
Usage: the "e" in e-mail (or email) should not be capitalized unless it is the
first word in a sentence. (Even though Email is more readable than email)
Usage: (please prove me wrong if I am) e-mail (or email) is a noun, not a verb.
So "please e-mail us" is incorrect and should be "please send us a e-mail".
wrong and incorrect:
usage: had to point this out because I just made this mistake (had '"please e-mail
us" is wrong'). Use "incorrect," "improper," "insufficient," etc.
log-in: noun e.g. "log-in is complete"
log in: verb e.g. "please log in"
Since "log in" is not a commonly used word (a person who knows little about
computer usually knows "e-mail" but doesn't know "log in"), the hyphen should
be retained.
log-off: noun
log off: verb
add-on: <-- just what the hack this is?
alert: all developers in www.mozdev.org
plug-in: <-- and this?
e.g. if Sherlock is a plug-in, what are the search engine things we add to
the Search sidebar?
Again, hyphen should be retained
helper application:
needs definition
performance
use with caution. see http://bugzilla.mozilla.org/show_bug.cgi?id=126600
while we are on the subject of "performance", here is a list of some defintions from
ISO 9000:2000 (slightly edited)
efficiency
relationship between the result achieved and the resources used
effectiveness
extent to which planned activities are realized and planned results achived
quality:
degree to which a set of inherent characteristics fulfils *requirements*
(/implied, stated, or oblgatory needs or expectation/)
quality assurance (QA):
part of quality management, focused on providing confidence that quality
requirements will be fulfilled
note: QA does not guarantee that quality will be achived, that's quality
control (QC)
document
*information* (/meaningful data/) and its supporting medium
specification
*document* stating *requirements*
verification
confirmation, the the provision of objective evidence, that specified
*requirements* have been fulfilled
validation
confirmation, the the provision of objective evidence, that the
*requirements* for a specific intended use or application have been
fulfilled
e.g. "verify the code against the specification"
e.g. "validate the code against the intended use"
shall, must, may, etc.
see http://www.ietf.org/rfc/rfc2119.txt
standard
see http://hebb.cis.uoguelph.ca/~dave/343/Lectures/standards.html
mozilla
a W3C standard-compliant browser?
or just another browser (what's up with document.all and marquee)?
or something that every other browser should have been?
lizard
what mozilla is - looks scary, but in fact is friendly :)
L. David Baron
> see http://bugzilla.mozilla.org/show_bug.cgi?id=53153
>
> For consistancy with (English) documentation, I think we need a style guide to
> word choices and grammar. Below is just a short list of words that we should
> watch out for. Feel free to add more entries. Also feel free to disagree with
> me.
http://developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/AppBTerms/index.html
is an example of such a style guide (it links to another guide that may
be more thorough, although it's in PDF format).
For what types of documentation are you suggesting we need such a style
guide? I can see the use of one for end-user documentation and for web
developer documentation, although the two would probably need different
guides. Then again, I only really see the advantage of such a level of
consistency in a world where we have more thorough docs than we do now.
-David
--
L. David Baron <URL: http://www.people.fas.harvard.edu/~dbaron/ >
Brant Langer Gurganus
> see http://bugzilla.mozilla.org/show_bug.cgi?id=53153
>
> For consistancy with (English) documentation, I think we need a style
> guide to
> word choices and grammar.
Below is just a short list of words that we
> should
> watch out for. Feel free to add more entries. Also feel free to disagree
> with
> me.
>
> e-mail and email: n. electronic mail
> Both variants are commonly accepted. The general public seems drop the
> hyphen
> while editors (and probably English professors) seems to favor
> "e-mail". (I favor
> "e-mail" because it retains the original meaning and because it's more
> readable.)
> However, since "email" is used in mozilla more than "e-mail" is, the
> hyphen-ized
> form should be used.
>
> Usage: the "e" in e-mail (or email) should not be capitalized unless
> it is the
> first word in a sentence. (Even though Email is more readable
> than email)
How about Internet (correct for the global network we all use) vs.
internet (any large network)
or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide Web
which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
Also, how about webmaster (correct) or web master (incorrect)?
--
Brant Langer Gurganus
Default QA Contact, Mozilla Evangelism
Technician, Protonic.com
Webmaster, troop545.cjb.net
Webmaster, www.firecrafter.org
Webmaster, www.msdpt.k12.in.us/etspages/ph
Junior Assistant Scoutmaster, Troop 545
Eagle Scout, Boy Scouts of America
Member, Internet Society
dwx
Where variant forms of a word or phrase exists, the most commonly
used form will be used.
(Some dictionaries indicate which form is the most commonly used.
We should choose one as our reference basis.)
Dash and hyphen
need something on the use of dash, hyphen, and spacing.
more words
tag
/pp/ part of speech (verb, noun, adjective, etec)
/dontuse/ don't use. A preferred word or phrase is given.
/avoid/ avoid. A preferred word or phrase is given.
/spell/ easily mis-spelled word or phrase
/proper/ proper name. Spell as is.
/comp/ compound phrase, such as "log-out" or "home page"
/var/ variant form
/ambig/ potentially ambiguous word
/use/ note on how to use the word (or phrase) in a given context
/def/ definition
/case/ case sensitive
note: compound noun or verb used as an adjective is always hyphenated
(e.g. end-user agreement)
please help define the following: add-on, plug-in, helper application,
help file, documentation
*home page* /comp/
Two words.
*log-in* /pp,comp/ [noun]
*log in* /pp/ [verb]
*log-off* /dontuse/
Don't use; use *log-out*
*log off* /dontuse/
Don't use; use *log out*
*log-on* /dontuse/
Don't use; use *log-in*
*log on* /dontuse/
Don't use; use *log in*
*log-out* /pp,comp/ [n]
*log out* /pp/ [v]
*performance* /ambig,avoid/
Avoid. Use more descriptive word or phrase such as "processing speed,"
"efficiency," or "robustness"
*Web site* /comp,def,case/ <- *request comment*
a domain, or part of a domain, consisting of a collection of hyperlinked
*Web pages*
*Web page* /comp,def,case/ <- *request comment*
a text document on the Web
[the following is based on a message from Jay Garcia in a thread called
"Tabbed Browsing?"]
*end user* /comp,def/
[n] the ultimate user of a product who is not a developer
"developer" /def/
[n] programmer, tester, documentation author, patch writer, etc.
[the following is from "Mac OS X Terminology Guidelines"
<http://developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/AppBTerms/index.html>]
*abort* /dontuse/
Don't use; use *cancel*.
*application* /spell/
It is not necessary to say "application program" on first use.
"Application" is OK to use alone.
*cancel*
Preferred form of *abort*
*cancelled* /var/
Note two "l."
*canceling* /var/
Note two "l."
*dialog* /use/
Use instead of "dialog box.
*directory* /ambig/
In user documentation, don't use directory when you can say folder.
*disable* /avoid/
Avoid in user documentation; say dimmed or turned off (or simply off).
(see *enable*)
*enable* /avoid/
Avoid in user documentation; say available or turned on (or simply on) or
selected. (see *disable*)
*filename* /comp,spell/
One word.
*Mac OS 9* /spell,proper,case/
Always use the full name; don't shorten to "OS 9" or "9." Note spacing
between each "word." Don't say "Mac OS 8/9"; instead say
"Mac OS 8 and Mac OS 9."
*Mac OS X* /spell,proper,case/
Always say "Mac OS X"; don't shorten to "OS X" or "X." Note spacing
*menu bar* /comp,spell/
Two words
*pane* /all/ *important*
Use to refer to different views within a window (views that can be changed with
a tab, a pop-up menu, a button, or by selecting an item, or views that change
automatically, as in Installer). In most cases in user documentation, you can
avoid using "pane" by describing how to get to a particular place: "Click System
Preferences, click Network, click AppleTalk...."
Examples of how to use "pane":
- [omit]
*panel* /dontuse/
Don't use; see pane and dialog.
*path* /use/
see *pathname*
*pathname* /use/
Most user documentation does not need to refer to specific pathnames ("[plug-ins
are in the Internet Plug-Ins folder in the System folder](edited)"). But when
necessary—if a user has to type a pathname in a dialog, for example—you can
refer to it as "the path" or "the pathname."
*screen shot* /comp,spell/
Two words. Don't use "screen dump."
*tab* /use/
In a *dialog*, the tab itself is called the "<tabname> tab," but the content you
see when you click a tab is the "*pane*." Don't say "under the <tabname> tab."
Examples:
You can specify your home page in the Web pane of Internet preferences.
To set up automatic login, click Login, then click the Login Window tab.
dwx
can be used as a verb?
> How about Internet (correct for the global network we all use) vs.
> internet (any large network)
good, but in documentation we should avoid such distinction
> or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide Web
> which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
acronym is "word fromed from the initial letters of a group of words"
WWW is an acronym. W3 is some fancy word that few understands.
> Also, how about webmaster (correct) or web master (incorrect)?
how about mark Webmaster as /avoid/? (see message titled
"Re: word usage... [documentation and GUI style guide]")
dwx
*e-mail* /spell,compound/
The hyphenated form, "E-mail," is the correct and therefore the preferred English
form. "E-mail", being itself a acronym of "electronic mail," should be considered
different from other unabbreviated compound nouns such as "pickup." Analogous to
"U-turn" and "A-bomb," both of which 1) are commonly used and 2) begin with a
separately pronounced letter, "E-mail" should be spelled with capital E and should
not be one-word-ized as "email."
Translation - Words with Foreign Origins
Languages evolve at different speeds. For example, a foreign word that has been
incorporated into a language may have undergone changes in its original language.
For example, in Taiwan the form "e-mail" is used almost twice as often as "email"
whereas in Mainland China "email" is used slighly more frequently than "e-mail."
In such a case where an incorporated word is spelled or used differently from
the word's usage in its original language, translators and localizers should use
what is most acceptable in their locale.
Brant Langer Gurganus
>> or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide Web
>> which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
> acronym is "word fromed from the initial letters of a group of words"
> WWW is an acronym. W3 is some fancy word that few understands.
information here from the inventor of the World Wide Web.
--
Brant Langer Gurganus
Editor, Open Directory Project
dwx
> dwx wrote:
>
>>> or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide
>>> Web which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
>>
>> acronym is "word fromed from the initial letters of a group of words"
>> WWW is an acronym. W3 is some fancy word that few understands.
>
> See http://www.w3.org/People/Berners-Lee/FAQ.html#Spelling for more
> information here from the inventor of the World Wide Web.
Tim Berners-Lee writes:
Often, WWW is written and read as W3, which is quicker to say. In particular,
the World Wide Web consortium is W3C, never WWWC.
Note that he both uses WWW and W3, and he doesn't mention which one is the
"correct" acronym. But to avoid confusion, I will say that we don't use either.
We need definitions for the Web and the Internet. Want to volunteer?
*Internet, the* /proper,def/
/Needs definition./ See also "*World Wide Web, the*/
*Net, the* /dontuse/
Don't use; spell it as *the Internet*. Don't abbreviate it as the Net.
*W3* /dontuse/
Don't use; either refer to it as "the Web" or "World Wide Web."
*web* /dontuse/
When referring to any form of electronic network of information, unless
it is World Wide Web, use the generic term "network" or a specific term
such as "intranet."
*Web, the* /proper/
It's "the Web," not "Web." See also "*Internet, the*"
*World Wide Web, the* /proper,def/
/Needs defintiion/ Abbreviate it as "the Web" but not as "WWW" or "W3."
See also "*Internet, the*."
*WWW* /dontuse/
Don't use; either refer to it as "the Web" or "World Wide Web."
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
Well, it was only a matter of time before I got involved in this. . . .
> see http://bugzilla.mozilla.org/show_bug.cgi?id=53153
>
> For consistancy with (English) documentation, I think we need a style
> guide to word choices and grammar. Below is just a short list of words
> that we should watch out for. Feel free to add more entries. Also feel
> free to disagree with me.
>
> e-mail and email: n. electronic mail
> Both variants are commonly accepted. The general public seems drop
> the hyphen while editors (and probably English professors) seems to
> favor "e-mail". (I favor "e-mail" because it retains the original
> meaning and because it's more readable.) However, since "email" is
> used in mozilla more than "e-mail" is, the hyphen-ized form should be
> used.
>
> Usage: the "e" in e-mail (or email) should not be capitalized unless
> it is the
> first word in a sentence. (Even though Email is more readable
> than email)
>
> Usage: (please prove me wrong if I am) e-mail (or email) is a noun,
> not a verb.
> So "please e-mail us" is incorrect and should be "please send
> us a e-mail".
>
> wrong and incorrect:
> usage: had to point this out because I just made this mistake (had
> '"please e-mail us" is wrong'). Use "incorrect," "improper,"
> "insufficient," etc.
My personal preference is for 'e-mail', hyphenated and /sans/ cap (which
/never/ made sense to me). Adding a cap ('E-mail' or 'Email') makes no
sense at all, since it would seem implicitly to turn it into a proper noun,
while 'email' doesn't make it clear that the 'e[lectronic]' is separate from
'mail'. Technically, /none/ of the shortened forms are correct, since 'e-
mail' itself would imply that it's functioning adjectivally ('e-mail
client'), but 'e-mail' strikes me as the best of a bad lot.
I see no problems with using 'e-mail' as a verb, in as much as 'mail' itself
can function both as a noun and an adjective. (BTW, you should've had 'an
e-mail. :-) )
Not sure what point would be served by drawing distinctions between 'wrong',
'incorrect', and 'improper'; you've given no adequate rationale for doing
so.
> log-in: noun e.g. "log-in is complete"
> log in: verb e.g. "please log in"
>
> Since "log in" is not a commonly used word (a person who knows
> little about computer usually knows "e-mail" but doesn't know "log
> in"), the hyphen should be retained.
Realistically, 'log-in' should be used in a qualifier ('log-in procedure');
any other usage should be unhyphenated.
> log-off: noun
> log off: verb
>
> add-on: <-- just what the hack this is?
> alert: all developers in www.mozdev.org
I'm not sure anyone's decided whether it should be 'add-on' or 'add-in'
(hyphens optional).
> plug-in: <-- and this?
> e.g. if Sherlock is a plug-in, what are the search engine things we
> add to the Search sidebar?
>
> Again, hyphen should be retained
Agreed.
> helper application:
> needs definition
?!
I think the following jumps the gun a bit. . . .
And so the argument begins again. . . .
/b.
--
Mozilla end-user questions should be directed to:
snews://secnews.netscape.com:563/netscape.mozilla.user.general
snews://secnews.netscape.com:563/netscape.mozilla.user.win32
snews://secnews.netscape.com:563/netscape.mozilla.user.mac
snews://secnews.netscape.com:563/netscape.mozilla.user.unix
Note that you need to have SSL enabled and the port set to 563.
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
>> I say e-mail is the noun and email is the verb.
> can you find any dictionary or style guide that says e-mail or email
> can be used as a verb?
To the extent that 'e[-]' modifies 'mail', and 'mail' (in the postal sense,
not the armour sense) is a verb as well as noun, I really don't have a
problem with using 'e-mail' as both a noun and a verb.
>> How about Internet (correct for the global network we all use) vs.
>> internet (any large network)
> good, but in documentation we should avoid such distinction
Functions as a proper noun (believe it or not), and so should be 'Internet'.
>> or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide Web
>> which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
> acronym is "word fromed from the initial letters of a group of words"
> WWW is an acronym. W3 is some fancy word that few understands.
Personally, I'd say forget about 'WWW'; just use 'Internet'. W3 is clear
enough, but is one of those annoying hyper-condensations; I'd say use it
only if the character 'C' follows (W3C).
>> Also, how about webmaster (correct) or web master (incorrect)?
> how about mark Webmaster as /avoid/? (see message titled
> "Re: word usage... [documentation and GUI style guide]")
How about finding a term that actually makes sense? Webmaster/Web master
and webmaster/web master always puts me in mind of Prof. Moriarty. It's
also stupidly gender specific.
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
> On Thursday 2002-08-01 19:42 -0700, dwx wrote:
>> see http://bugzilla.mozilla.org/show_bug.cgi?id=53153
>>
>> For consistancy with (English) documentation, I think we need a style
>> guide to word choices and grammar. Below is just a short list of words
>> that we should watch out for. Feel free to add more entries. Also feel
>> free to disagree with me.
>
> http://developer.apple.com/techpubs/macosx/Essentials/AquaHIGuidelines/Ap
> pBTerms/index.html is an example of such a style guide (it links to
> another guide that may be more thorough, although it's in PDF format).
>
> For what types of documentation are you suggesting we need such a style
> guide? I can see the use of one for end-user documentation and for web
> developer documentation, although the two would probably need different
> guides. Then again, I only really see the advantage of such a level of
> consistency in a world where we have more thorough docs than we do now.
>
> -David
The more I think about this, the more I think we've ended up putting the
cart before the horse; /i.e./, that it might have been a tactical error to
go ahead with working on developer/tech docs before getting user docs out of
the way.
Both are imperative. In the long run, dev/tech docs are, of course, more
important. User/web-dev docs (and this would include whatever work needs
to be done on the help file), however, should be easier to produce -- and to
maintain.
It's increasingly evident that the lack of user docs in particular are
having a more-than-passingly negative impact on some of the n.p.m.* groups.
A lot of these people won't bother going to the n.m.u.* groups, no matter
how often you direct them there, but if you could at least say 'Here, RTFM',
that would clear up a lot of grief.
Just a thought, albeit one born of increasing frustration.
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
> dwx wrote:
>>> or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide Web
>>> which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
>> acronym is "word fromed from the initial letters of a group of words"
>> WWW is an acronym. W3 is some fancy word that few understands.
> See http://www.w3.org/People/Berners-Lee/FAQ.html#Spelling for more
> information here from the inventor of the World Wide Web.
You *do* realise that Dr Berners-Lee disagrees with you, right?
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
> Brant Langer Gurganus wrote:
>> dwx wrote:
>>
>>>> or WWW (incorrect acronym) vs. W3 (correct acronym) for World Wide
>>>> Web which isn't world-wide web or worldwide web. Ask Tim Bernes-Lee
>>>
>>> acronym is "word fromed from the initial letters of a group of words"
>>> WWW is an acronym. W3 is some fancy word that few understands.
>>
>> See http://www.w3.org/People/Berners-Lee/FAQ.html#Spelling for more
>> information here from the inventor of the World Wide Web.
>
> Tim Berners-Lee writes:
> Often, WWW is written and read as W3, which is quicker to say. In
> particular, the World Wide Web consortium is W3C, never WWWC.
>
> Note that he both uses WWW and W3, and he doesn't mention which one is
> the "correct" acronym. But to avoid confusion, I will say that we don't
> use either.
>
> We need definitions for the Web and the Internet. Want to volunteer?
>
> *Internet, the* /proper,def/
> /Needs definition./ See also "*World Wide Web, the*/
> *Net, the* /dontuse/
> Don't use; spell it as *the Internet*. Don't abbreviate it as the
> Net.
Nothing wrong with using it if you prefix it with an apostrophe: 'Net
(really, it should be ’Net, but I'll not go there). But as a rule of
thumb, there would be few cases where it would be preferrable.
> *W3* /dontuse/
> Don't use; either refer to it as "the Web" or "World Wide Web."
> *web* /dontuse/
> When referring to any form of electronic network of information,
> unless it is World Wide Web, use the generic term "network" or a
> specific term such as "intranet."
> *Web, the* /proper/
> It's "the Web," not "Web." See also "*Internet, the*"
You can already see that this is gonna cause problems. David Gerard and I
wrangled with this one while working on the 1.0 FAQs; 'web' works better
than 'Web', tho' I'd still prefer to see 'Internet' used in most cases.
> *World Wide Web, the* /proper,def/
> /Needs defintiion/ Abbreviate it as "the Web" but not as "WWW" or
> "W3." See also "*Internet, the*."
> *WWW* /dontuse/
> Don't use; either refer to it as "the Web" or "World Wide Web."
/b.
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
> see http://bugzilla.mozilla.org/show_bug.cgi?id=53153#c16
>
> *e-mail* /spell,compound/
> The hyphenated form, "E-mail," is the correct and therefore the
> preferred English form. "E-mail", being itself a acronym of "electronic
> mail," should be considered different from other unabbreviated compound
> nouns such as "pickup." Analogous to "U-turn" and "A-bomb," both of
> which 1) are commonly used and 2) begin with a separately pronounced
> letter, "E-mail" should be spelled with capital E and should not be
> one-word-ized as "email."
WTF does this have to do with anything?
> Translation - Words with Foreign Origins
> Languages evolve at different speeds. For example, a foreign word that
> has been incorporated into a language may have undergone changes in its
> original language. For example, in Taiwan the form "e-mail" is used
> almost twice as often as "email" whereas in Mainland China "email" is
> used slighly more frequently than "e-mail." In such a case where an
> incorporated word is spelled or used differently from the word's usage
> in its original language, translators and localizers should use what is
> most acceptable in their locale.
/b.
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
> Variants of spelling (cancelled, color, etc.)
> Where variant forms of a word or phrase exists, the most commonly
> used form will be used.
> (Some dictionaries indicate which form is the most commonly used.
> We should choose one as our reference basis.)
Given the over-whelming American presence in this project, I'd suggest using
American conventions for spelling, punctuation, &c, the one notable
exception being dashes, where the Continental style (en-dash set off by
spaces) is probably preferrable.
> Dash and hyphen
> need something on the use of dash, hyphen, and spacing.
Just about any style guide out there will explain the distinction between a
dash and hyphen in excruciating detail. Use an en-dash rather than an em-
dash where appropriate.
> more words
>
> tag
> /pp/ part of speech (verb, noun, adjective, etec)
> /dontuse/ don't use. A preferred word or phrase is given.
> /avoid/ avoid. A preferred word or phrase is given.
> /spell/ easily mis-spelled word or phrase
> /proper/ proper name. Spell as is.
> /comp/ compound phrase, such as "log-out" or "home page"
> /var/ variant form
> /ambig/ potentially ambiguous word
> /use/ note on how to use the word (or phrase) in a given
> context /def/ definition
> /case/ case sensitive
>
> note: compound noun or verb used as an adjective is always hyphenated
> (e.g. end-user agreement)
Of course.
> please help define the following: add-on, plug-in, helper application,
> help file, documentation
>
> *home page* /comp/
> Two words.
> *log-in* /pp,comp/ [noun]
> *log in* /pp/ [verb]
> *log-off* /dontuse/
> Don't use; use *log-out*
> *log off* /dontuse/
> Don't use; use *log out*
> *log-on* /dontuse/
> Don't use; use *log-in*
> *log on* /dontuse/
> Don't use; use *log in*
> *log-out* /pp,comp/ [n]
> *log out* /pp/ [v]
Just out of curiosity, why your emphatic distaste for 'log[-]on' and 'log[-
]off'?
All right. This is gonna end up a big heap of trouble. While I'm sure most
of us appreciate the energy you're putting in to this -- and while there is
certainly good material here -- , the way in which you're going about it is
problematic. It's beginning to come across a bit dictatorial; perhaps
that's 'cos you're trying to hash things thro' too quickly. There are far
too many things here that are simply stated without any explanation. Since
no-one seems to've given a half-assed decent reason to prefer 'Web' to
'web', I see no reason to be told to write 'Web site'.
Er, I only see one 'l' there. Not doubling characters in cases like this
is, AFAICT, the more common American spelling.
The point of a style guide is to introduce uniformity into documentation.
Would it not make sense to make use of the conventions to which most of the
people who will be writing the documentation are already accustomed?
> *dialog* /use/
> Use instead of "dialog box.
<personalAside>
David Gerard (an Aussie) and I (a Canuck) hashed this one thro' a while ago;
I don't think either of us were thrilled with settling on 'dialog' (in my
case 'cos it means I end up typing 'dialogue' and then deleting the last two
characters on a regular basis), but a lot of simply using 'dialog' depends
on phrasing; see, /e.g./, <http://mozilla.org/start/1.0/faq/mail-
news.html#3.7>: 'Open Mail/News and go to Tools | Import, which will bring
up a dialog to guide you through the process.'
</personalAside>
> *directory* /ambig/
> In user documentation, don't use directory when you can say
> folder.
No. Use 'directory' in place of 'folder', since the former is more
universal across multiple platforms, whilst the latter tends to be more OS-
specific. (/Verb. sap./: *Never* use the term 'folder' when talking to a
'Nix user.)
> *disable* /avoid/
> Avoid in user documentation; say dimmed or turned off (or simply
> off). (see *enable*)
WTF?! -- Why?
> *enable* /avoid/
> Avoid in user documentation; say available or turned on (or simply
> on) or selected. (see *disable*)
WTF?! -- Why?
> *filename* /comp,spell/
> One word.
WTF?! -- Why?
> *Mac OS 9* /spell,proper,case/
> Always use the full name; don't shorten to "OS 9" or "9." Note
> spacing between each "word." Don't say "Mac OS 8/9"; instead say
> "Mac OS 8 and Mac OS 9."
WTF?! I can understand using 'Mac OS /x/', tho' I've yet to come across a
Mac user who had to have it spelled out that he/she was using a Mac, but the
shorthand '[Mac] OS 8/9' is much more sane.
> *Mac OS X* /spell,proper,case/
> Always say "Mac OS X"; don't shorten to "OS X" or "X." Note
> spacing
WTF?!
> *menu bar* /comp,spell/
> Two words
> *pane* /all/ *important*
> Use to refer to different views within a window (views that can be
> changed with a tab, a pop-up menu, a button, or by selecting an
> item, or views that change automatically, as in Installer). In
> most cases in user documentation, you can avoid using "pane" by
> describing how to get to a particular place: "Click System
> Preferences, click Network, click AppleTalk...."
'Pane' (or 'panel') has a specific use in the context of Mozilla.
> Examples of how to use "pane":
> - [omit]
> *panel* /dontuse/
> Don't use; see pane and dialog.
And why not?
> *path* /use/
> see *pathname*
> *pathname* /use/
> Most user documentation does not need to refer to specific
> pathnames ("[plug-ins are in the Internet Plug-Ins folder in the
> System folder](edited)"). But when necessary擁f a user has to type
> a pathname in a dialog, for example遥ou can refer to it as "the
> path" or "the pathname."
Thank you for your graciousness in letting describe things accurately.
BTW, em-dashes don't work very well in cases like the above (especially in
plain text); use 'example -- you' or 'example---you' instead. If we're
talking about HTML, em-dashes /still/ don't work; use an en-dash set off by
spaces in stead.
> *screen shot* /comp,spell/
> Two words. Don't use "screen dump."
> *tab* /use/
> In a *dialog*, the tab itself is called the "<tabname> tab," but
> the content you see when you click a tab is the "*pane*." Don't
> say "under the <tabname> tab."
>
> Examples:
> You can specify your home page in the Web pane of Internet
> preferences. To set up automatic login, click Login, then click
> the Login Window tab.
All right. I give up. Give me an e-mail address where I can send you all
the 'FAQs' material I was gathering for additional user documentation and
I'll forward it to you. I'll get hold of David Gerard's various FAQ piles
as well and send them your way.
This is just plain f***ing stupid. Some of your points are well taken, but
/far/ too many of them are either wrong or an expression of personal
preference for me even to bother to conform.
dwx
> The more I think about this, the more I think we've ended up putting the
> cart before the horse; /i.e./, that it might have been a tactical error
> to go ahead with working on developer/tech docs before getting user docs
> out of the way.
>
> Both are imperative. In the long run, dev/tech docs are, of course,
> more important. User/web-dev docs (and this would include whatever work
> needs to be done on the help file), however, should be easier to produce
> -- and to maintain.
>
> It's increasingly evident that the lack of user docs in particular are
> having a more-than-passingly negative impact on some of the n.p.m.*
> groups. A lot of these people won't bother going to the n.m.u.* groups,
> no matter how often you direct them there, but if you could at least say
> 'Here, RTFM', that would clear up a lot of grief.
>
> Just a thought, albeit one born of increasing frustration.
>
> /b.
The style guide (a more /friendly/ version underway) should be for end-user
documentations only. For developer documentations, whatever convensions there
are should take precedence.
I could help with end-user documentations, but I will need someone who knows
who is doing what to tell me what I should be working on.
And Brian Heinrich, you may send whatever links or files you want to
danielw...@aol.com
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
>
>> The more I think about this, the more I think we've ended up putting
>> the cart before the horse; /i.e./, that it might have been a tactical
>> error to go ahead with working on developer/tech docs before getting
>> user docs out of the way.
>>
>> Both are imperative. In the long run, dev/tech docs are, of course,
>> more important. User/web-dev docs (and this would include whatever
>> work needs to be done on the help file), however, should be easier to
>> produce -- and to maintain.
>>
>> It's increasingly evident that the lack of user docs in particular are
>> having a more-than-passingly negative impact on some of the n.p.m.*
>> groups. A lot of these people won't bother going to the n.m.u.*
>> groups, no matter how often you direct them there, but if you could at
>> least say 'Here, RTFM', that would clear up a lot of grief.
>>
>> Just a thought, albeit one born of increasing frustration.
>>
>> /b.
>
> The style guide (a more /friendly/ version underway) should be for
> end-user documentations only. For developer documentations, whatever
> convensions there are should take precedence.
Hmm . . . methinks you're missing the point.
> I could help with end-user documentations, but I will need someone who
> knows who is doing what to tell me what I should be working on.
Right now a lot of end-user d11n is kind of in limbo between David Gerard
and myself. (Hmm . . . haven't seen Jayesh around of late. . . .)
> And Brian Heinrich, you may send whatever links or files you want to
> danielw...@aol.com
After having read David Baron's response to a different posting of mine,
I'll hold off for the moment. While I do agree that a style guide is
necessary -- and not just for end-user d11n -- , it's one of those things
that's got to evolve /from/ the process; it can't be imposed from the
outset.
My apologies for my venting of spleen, but some of what you were suggesting
/really/ rubbed me the wrong way.
dwx
Brian Heinrich wrote:
> On 01 Aug 2002, it is alleged that dwx sauntered in to
> netscape.public.mozilla.documentation and loudly proclaimed:
>
>> Variants of spelling (cancelled, color, etc.)
>> Where variant forms of a word or phrase exists, the most commonly
>> used form will be used.
>> (Some dictionaries indicate which form is the most commonly used.
>> We should choose one as our reference basis.)
>
>
> Given the over-whelming American presence in this project, I'd suggest
> using American conventions for spelling, punctuation, &c, the one
> notable exception being dashes, where the Continental style (en-dash set
> off by spaces) is probably preferrable.
>
okay.
> [snip]
> Just out of curiosity, why your emphatic distaste for 'log[-]on' and 'log[-
> ]off'?
-delete- I just stole the stuff from Apple's style guide. Personally I have got
no problem with logon & logoff ('cuz I've never seem them used).
> [snip]
> The point of a style guide is to introduce uniformity into
> documentation. Would it not make sense to make use of the conventions
> to which most of the people who will be writing the documentation are
> already accustomed?
Right. Should have done word counts before I putting anything in...
>> *dialog* /use/
>> Use instead of "dialog box.
>
>
> <personalAside>
> David Gerard (an Aussie) and I (a Canuck) hashed this one thro' a while
> ago; I don't think either of us were thrilled with settling on 'dialog'
> (in my case 'cos it means I end up typing 'dialogue' and then deleting
> the last two characters on a regular basis), but a lot of simply using
> 'dialog' depends on phrasing; see, /e.g./,
> <http://mozilla.org/start/1.0/faq/mail-
> news.html#3.7>: 'Open Mail/News and go to Tools | Import, which will
> bring up a dialog to guide you through the process.'
> </personalAside>
-delete- (never seen 'dialog box' being used anyway)
>> *directory* /ambig/
>> In user documentation, don't use directory when you can say
>> folder.
>
>
> No. Use 'directory' in place of 'folder', since the former is more
> universal across multiple platforms, whilst the latter tends to be more OS-
> specific. (/Verb. sap./: *Never* use the term 'folder' when talking to
> a 'Nix user.)
sorry, stole that from Apple's style guide w/o thinking...
> [snip]
> WTF?! -- Why?
> [snip]
> WTF?! -- Why?
> [snip]
> WTF?! -- Why?
because I stole those from Apple's style guide w/o thinking...
> WTF?! I can understand using 'Mac OS /x/', tho' I've yet to come across
> a Mac user who had to have it spelled out that he/she was using a Mac,
> but the shorthand '[Mac] OS 8/9' is much more sane.
from Apple's style guide (which I think should be respected)...
>> *Mac OS X* /spell,proper,case/
>> Always say "Mac OS X"; don't shorten to "OS X" or "X." Note
>> spacing
>
>
> WTF?!
>
sorry, stole that from Apple's style guide w/o thinking...
> [snip]
Brian Heinrich
netscape.public.mozilla.documentation and loudly proclaimed:
All right. Fair enough on that point, I s'pose; I just find it needlessly
redundant. It's most common to use the 'Mac' in 'Mac OS', but there are
times when I find /that/ needlessly rendundant as well.
Part of that -- and that would include OS X as well -- is simply that the
few Mac users I know drop the 'Mac' as being, well, needlessly redundant. :-
P
/b.
>>> *Mac OS X* /spell,proper,case/
>>> Always say "Mac OS X"; don't shorten to "OS X" or "X." Note
>>> spacing
>>
>>
>> WTF?!
>>
> sorry, stole that from Apple's style guide w/o thinking...
>
>> [snip]
>> This is just plain f***ing stupid. Some of your points are well taken,
>> but /far/ too many of them are either wrong or an expression of
>> personal preference for me even to bother to conform.
>>
>> /b.
>>
>
>
--
Gervase Markham
> For example:
> <span lang="en-US">color</span>
> or
> <span lang="en-GB">colour</span>
Why? Does any browser do anything different with this? Does anyone really have time to implement a system to serve the correct spellings to each type of user? This seems like using it for the sake of it, rather than any practical benefit.
My policy statement:
"There are differences. Cope."
:-)
Gerv
Brant Langer Gurganus
>> We should use <span lang=""> where necessary when regionalities occur.
>> For example:
>> <span lang="en-US">color</span>
>> or
>> <span lang="en-GB">colour</span>
>
>
> Why? Does any browser do anything different with this? Does anyone
> really have time to implement a system to serve the correct spellings to
> each type of user? This seems like using it for the sake of it, rather
> than any practical benefit.
Miscellaneous Properites: Language: English or something similar.
And yes, for the most part, I am using it for the sake of it because I
am a web standard idealist. Just because nothing much is done now with
the property doesn't mean something won't be done in the future. What's
the point of using <link> elements when Mozilla is the only browser to
my knowledge to support them, and only in the nightly builds.
Alex Vincent
news:aj7tkc$q2...@ripley.netscape.com...
> Why? Does any browser do anything different with this? Does anyone really
have time to implement a system to serve the >correct spellings to each type
of user? This seems like using it for the sake of it, rather than any
practical benefit.
I agree with Gerv. The idea of enforcing a particular word choice -- when
the context of the word's usage, the sentences and subject matter around it
will make it clear -- will cause more headaches than benefit.
We want to keep it simple to write documentation, and this is a dangerous
idea towards boggling it down. I would say we should attempt to exclude any
sort of attempts to build a mozilla.org official spelling guide, except to
insist that it be correct in one language or another, and not be a
profanity.
dwx
> I agree with Gerv. The idea of enforcing a particular word choice -- when
> the context of the word's usage, the sentences and subject matter around it
> will make it clear -- will cause more headaches than benefit.
>
> We want to keep it simple to write documentation, and this is a dangerous
> idea towards boggling it down. I would say we should attempt to exclude any
> sort of attempts to build a mozilla.org official spelling guide, except to
> insist that it be correct in one language or another, and not be a
> profanity.
A style guide, official or non-official, is a guidelines (level 3
from the ISO 9000 point of view) document, not a specification (level 2).
Unless a higher level document dictates that the style guide "shall" be
used, documentation writers may use it at their own discretion.
I do not like the argument that "as long as it is correct language, it is
okay." A document is acceptable if its language is consistent, accurate,
and grammatically correct and serves the needs of the intended audience.
A style guide would serve this purpose.
(I do agree with Gervase Markham that "The form used by the document
author should be used, because both are as correct as each other.")
I guess most documentation contributors already use style guides. A Mozilla
style guide (again, official or non-official) would therefore be just another
style guide, except it is readily available to everyone.
In reply to all the comments about variant spelling, I apologize for rushing
into judgment in my early postings. I have changed my mind about this several
times since starting this thread and have settled down to this: it doesn't
matter, use either British English or U.S. English.
In reply to Brant Langer Gurganus, I would say inline designation of language
is an overkill. Be consistent and write a document in one language only. If
you want to use the lang attribute, put it in the <html> or <body> element.
Similarly, do not use <acronym>, <abbr>, title, and the like just for their
own sake. Avoid the use of jargons. If you must, provide a definition and
make sure the reader can infer their meanings from context.
Brant Langer Gurganus
> We want to keep it simple to write documentation, and this is a dangerous
> idea towards boggling it down. I would say we should attempt to exclude any
> sort of attempts to build a mozilla.org official spelling guide, except to
> insist that it be correct in one language or another, and not be a
> profanity.
a document should be consistent in spelling. This includes when edited
at a later time by another person.