Support:Style Guide: Difference between revisions
Jump to navigation
Jump to search
(fix proper noun) |
(organize into sections, add whitespace) |
||
| Line 1: | Line 1: | ||
The support.mozilla.com style guide aims to make the Firefox support Knowledge Base consistent, resulting in a knowledge base, that is easy to read and contribute to. These are not rigid rules. If you feel you have good reason not to follow any of these guidelines, feel free not to follow them. Conversely, do not be surprised if your contributions are edited, to comply the style guide. | The support.mozilla.com style guide aims to make the Firefox support Knowledge Base consistent, resulting in a knowledge base, that is easy to read and contribute to. These are not rigid rules. If you feel you have good reason not to follow any of these guidelines, feel free not to follow them. Conversely, do not be surprised if your contributions are edited, to comply the style guide. | ||
==Terminology== | |||
In cases where you are not sure of proper terminology, or if an element has more than one name, use the term in the user-interface. For instance, in the customize toolbar screen, the term used for the location bar is "Location" bar, not "Address" bar, or "URL" bar. Other often used terms: | In cases where you are not sure of proper terminology, or if an element has more than one name, use the term in the user-interface. For instance, in the customize toolbar screen, the term used for the location bar is "Location" bar, not "Address" bar, or "URL" bar. Other often used terms: | ||
*It's "web feeds", not "RSS feeds". | *It's "web feeds", not "RSS feeds". | ||
| Line 17: | Line 9: | ||
*Web site is two words, not one. | *Web site is two words, not one. | ||
===Common inconsistencies=== | |||
*Plug-ins contains a hyphen (it is not plugins).<br/> | |||
*Add-ons contains a hyphen (it is not addons). | |||
*Links to the main Mozilla.com web site should not contain the locale. | |||
**<span style="color: #006600">Good</span>: http://www.mozilla.com/firefox | |||
**Bad: http://www.mozilla.com/en-US/firefox | |||
= | ===Acronyms and Abbreviations=== | ||
==Acronyms and Abbreviations== | |||
When using a term, that may be presented as an acronym or abbreviation, use the method of presentation that is used in the user-interface; and do not separate the letters of an acronym by a period. | When using a term, that may be presented as an acronym or abbreviation, use the method of presentation that is used in the user-interface; and do not separate the letters of an acronym by a period. | ||
*<span style="color: #006600">Good</span>: SSL 3.0 | *<span style="color: #006600">Good</span>: SSL 3.0 | ||
| Line 44: | Line 22: | ||
*Bad: Secure Sockets Layer 3.0 | *Bad: Secure Sockets Layer 3.0 | ||
==Article Title/Section Capitalization== | |||
When creating the name of an article, capitalize the first word and any proper nouns. | |||
*<span style="color: #006600">Good</span>: How to make Firefox your default browser | |||
*Bad: How To Make Firefox Your Default Browser | |||
==Dates== | |||
*For dates use the format: January 1, 1990. | |||
**<span style="color: #006600">Good</span>: December 31, 2007 | |||
**Bad: December 31st, 2007 | |||
**Bad: 31 December, 2007 | |||
== | *Alternatively, you can use YYYY-MM-DD | ||
**<span style="color: #006600">Good</span>: 2007-12-31 | |||
**Bad: 31-12-2007 | |||
**Bad: 12-31-2007 | |||
==General spelling, grammar, and punctuation== | |||
United States English spelling is preferred. | United States English spelling is preferred. | ||
*<span style="color: #006600">Good</span>: color | *<span style="color: #006600">Good</span>: color | ||
| Line 52: | Line 45: | ||
If you're unsure of spelling, refer to [http://www.answers.com Answers.com]. | If you're unsure of spelling, refer to [http://www.answers.com Answers.com]. | ||
==Whitespace== | |||
* One newline after section titles, two before. | |||
* Two newlines between paragraphs | |||
* One newline after lists | |||
== | ===Latin abbreviations=== | ||
Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and in notes. Use periods in these abbreviations. | Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and in notes. Use periods in these abbreviations. | ||
*<span style="color: #006600">Good</span>: Search engines (e.g. Google) can be used ... | *<span style="color: #006600">Good</span>: Search engines (e.g. Google) can be used ... | ||
| Line 70: | Line 57: | ||
*Bad: Search engines, (eg: Google) can be used ... | *Bad: Search engines, (eg: Google) can be used ... | ||
===Plurals of acronyms and abbreviations=== | |||
==Plurals of acronyms and abbreviations== | |||
For plurals of acronyms or abbreviations, add s, without the apostrophe. | For plurals of acronyms or abbreviations, add s, without the apostrophe. | ||
*<span style="color: #006600">Good</span>: CD-ROMs | *<span style="color: #006600">Good</span>: CD-ROMs | ||
*Bad: CD-ROM's | *Bad: CD-ROM's | ||
===Pluralization=== | |||
==Pluralization== | |||
Use English-style plurals, not the Latin- or Greek-influenced forms. | Use English-style plurals, not the Latin- or Greek-influenced forms. | ||
*<span style="color: #006600">Good</span>: viruses | *<span style="color: #006600">Good</span>: viruses | ||
*Bad | *Bad virii | ||
===Serial commas=== | |||
Use the serial comma. The serial (also known as "Oxford") comma is the comma that appears before "and" in a series of three or more items. | |||
*<span style="color: #006600">Good</span>: Clear your cache, cookies, and history. | |||
*Bad: Clear your cache, cookies and history. | |||
== | ==Common formatting thingies== | ||
===Preference names / values=== | |||
[We still need to figure out what we can do with this on tikiwiki.] | |||
===User scripts (user.js, userChrome.css, userContent.css)=== | |||
[We still need to figure out what we can do with this on tikiwiki.] | |||
===File names / paths=== | |||
File names and file paths should presented in italics. | |||
===Keyboard shortcuts=== | |||
[We still need to figure out what we can do with this on tikiwiki.] | |||
===Menu paths=== | |||
[We still need to figure out what we can do with this on tikiwiki.] | |||
== | ==References== | ||
Links to any bug pages on Bugzilla should be treated as references. [We still need to figure out what we can do with this on tikiwiki.] | |||
Revision as of 20:49, 4 July 2007
The support.mozilla.com style guide aims to make the Firefox support Knowledge Base consistent, resulting in a knowledge base, that is easy to read and contribute to. These are not rigid rules. If you feel you have good reason not to follow any of these guidelines, feel free not to follow them. Conversely, do not be surprised if your contributions are edited, to comply the style guide.
Terminology
In cases where you are not sure of proper terminology, or if an element has more than one name, use the term in the user-interface. For instance, in the customize toolbar screen, the term used for the location bar is "Location" bar, not "Address" bar, or "URL" bar. Other often used terms:
- It's "web feeds", not "RSS feeds".
- It's "search engines", not "search plug-ins".
- Home page is two words, not one.
- Web site is two words, not one.
Common inconsistencies
- Plug-ins contains a hyphen (it is not plugins).
- Add-ons contains a hyphen (it is not addons).
- Links to the main Mozilla.com web site should not contain the locale.
Acronyms and Abbreviations
When using a term, that may be presented as an acronym or abbreviation, use the method of presentation that is used in the user-interface; and do not separate the letters of an acronym by a period.
- Good: SSL 3.0
- Bad: S.S.L. 3.0
- Bad: Secure Sockets Layer 3.0
Article Title/Section Capitalization
When creating the name of an article, capitalize the first word and any proper nouns.
- Good: How to make Firefox your default browser
- Bad: How To Make Firefox Your Default Browser
Dates
- For dates use the format: January 1, 1990.
- Good: December 31, 2007
- Bad: December 31st, 2007
- Bad: 31 December, 2007
- Alternatively, you can use YYYY-MM-DD
- Good: 2007-12-31
- Bad: 31-12-2007
- Bad: 12-31-2007
General spelling, grammar, and punctuation
United States English spelling is preferred.
- Good: color
- Bad: colour
If you're unsure of spelling, refer to Answers.com.
Whitespace
- One newline after section titles, two before.
- Two newlines between paragraphs
- One newline after lists
Latin abbreviations
Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and in notes. Use periods in these abbreviations.
- Good: Search engines (e.g. Google) can be used ...
- Bad: Search engines e.g. Google can be used ...
- Bad: Search engines, e.g. Google, can be used ...
- Bad: Search engines, (eg: Google) can be used ...
Plurals of acronyms and abbreviations
For plurals of acronyms or abbreviations, add s, without the apostrophe.
- Good: CD-ROMs
- Bad: CD-ROM's
Pluralization
Use English-style plurals, not the Latin- or Greek-influenced forms.
- Good: viruses
- Bad virii
Serial commas
Use the serial comma. The serial (also known as "Oxford") comma is the comma that appears before "and" in a series of three or more items.
- Good: Clear your cache, cookies, and history.
- Bad: Clear your cache, cookies and history.
Common formatting thingies
Preference names / values
[We still need to figure out what we can do with this on tikiwiki.]
User scripts (user.js, userChrome.css, userContent.css)
[We still need to figure out what we can do with this on tikiwiki.]
File names / paths
File names and file paths should presented in italics.
Keyboard shortcuts
[We still need to figure out what we can do with this on tikiwiki.]
Menu paths
[We still need to figure out what we can do with this on tikiwiki.]
References
Links to any bug pages on Bugzilla should be treated as references. [We still need to figure out what we can do with this on tikiwiki.]