Support:Style Guide: Difference between revisions
(remove sections which belong in best practices) |
(put 'good' examples in bold) |
||
| Line 17: | Line 17: | ||
==Links to Mozilla.com== | ==Links to Mozilla.com== | ||
Links to the main Mozilla.com web site should not contain the locale. | Links to the main Mozilla.com web site should not contain the locale. | ||
* <span style="color: #006600">Good</span>: http://www.mozilla.com/firefox | * '''<span style="color: #006600">Good</span>''': http://www.mozilla.com/firefox | ||
* Bad: http://www.mozilla.com/en-US/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 | ||
* Bad: S.S.L. 3.0 | * Bad: S.S.L. 3.0 | ||
* Bad: Secure Sockets Layer 3.0 | * Bad: Secure Sockets Layer 3.0 | ||
| Line 28: | Line 28: | ||
===Acronyms not found in the user-interface=== | ===Acronyms not found in the user-interface=== | ||
In cases where an acronym is not in the user-interface, introduce its expansion in parenthesis on the first mention. | In cases where an acronym is not in the user-interface, introduce its expansion in parenthesis on the first mention. | ||
* <span style="color: #006600">Good</span>: RSS(Really Simple Syndication) links | * '''<span style="color: #006600">Good</span>''': RSS(Really Simple Syndication) links | ||
* Bad: RSS links | * Bad: RSS links | ||
===Abbreviations not found in the user-interface=== | ===Abbreviations not found in the user-interface=== | ||
In cases where an abbreviation is not in the user-interface, use the long version. | In cases where an abbreviation is not in the user-interface, use the long version. | ||
* <span style="color: #006600">Good</span>: information | * '''<span style="color: #006600">Good</span>''': information | ||
* Bad: info | * Bad: info | ||
===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 | ||
==Capitalization in article title and sections== | ==Capitalization in article title and sections== | ||
When creating the name of an article, capitalize the first word and any proper nouns. | 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 | * '''<span style="color: #006600">Good</span>''': How to make Firefox your default browser | ||
* Bad: How to make Firefox your default browser | * Bad: How to make Firefox your default browser | ||
| Line 49: | Line 49: | ||
==Dates== | ==Dates== | ||
*For dates use the format: January 1, 1990. | * For dates use the format: January 1, 1990. | ||
**<span style="color: #006600">Good</span>: December 31, 2007 | ** '''<span style="color: #006600">Good</span>''': December 31, 2007 | ||
**Bad: December 31st, 2007 | ** Bad: December 31st, 2007 | ||
**Bad: 31 December, 2007 | ** Bad: 31 December, 2007 | ||
*Alternatively, you can use YYYY-MM-DD | * Alternatively, you can use YYYY-MM-DD | ||
**<span style="color: #006600">Good</span>: 2007-12-31 | ** '''<span style="color: #006600">Good</span>''': 2007-12-31 | ||
**Bad: 31-12-2007 | ** Bad: 31-12-2007 | ||
**Bad: 12-31-2007 | ** Bad: 12-31-2007 | ||
==Whitespace== | ==Whitespace== | ||
| Line 66: | Line 66: | ||
==General spelling, grammar, and punctuation== | ==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 | ||
*Bad: colour | * Bad: colour | ||
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]. | ||
| Line 73: | Line 73: | ||
===Latin abbreviations=== | ===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 ... | ||
*Bad: 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, e.g. Google, can be used ... | ||
*Bad: Search engines, (eg: Google) can be used ... | * Bad: Search engines, (eg: Google) can be used ... | ||
===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 virii | * Bad virii | ||
===Serial commas=== | ===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. | 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. | * '''<span style="color: #006600">Good</span>''': Clear your cache, cookies, and history. | ||
*Bad: Clear your cache, cookies and history. | * Bad: Clear your cache, cookies and history. | ||
==Common types of text== | ==Common types of text== | ||
Revision as of 07:08, 5 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.
Preferred style guides
If you have questions about usage and style not covered here, I recommend referring to the Economist style guide or, failing that, the Chicago Manual of Style.
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:
- Plug-ins contains a hyphen (it is not plugins).
- Add-ons contains a hyphen (it is not addons).
- 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.
Links to Mozilla.com
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
Acronyms not found in the user-interface
In cases where an acronym is not in the user-interface, introduce its expansion in parenthesis on the first mention.
- Good: RSS(Really Simple Syndication) links
- Bad: RSS links
Abbreviations not found in the user-interface
In cases where an abbreviation is not in the user-interface, use the long version.
- Good: information
- Bad: info
Plurals of acronyms and abbreviations
For plurals of acronyms or abbreviations, add s, without the apostrophe.
- Good: CD-ROMs
- Bad: CD-ROM's
Capitalization in article title and sections
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
(We may need a rule on special characters depending on how TikiWiki makes pretty URLs)
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
Whitespace
- One newline after section titles, two before.
- Two newlines between paragraphs
- One newline after lists
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.
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 ...
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 types of text
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.]