In-house style: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
(→‎Commonly used names and terms: - avoid "Mozilla Mail")
(use separate categories for general/browser/mail terms)
Line 11: Line 11:
* As stated in the [[Rules]], make sure to follow the new naming conventions for article titles that apply to more than one application.
* As stated in the [[Rules]], make sure to follow the new naming conventions for article titles that apply to more than one application.


==Commonly used names and terms==
==Commonly used names==
* '''Application names.''' Use "Firefox" (but not "FireFox"), "Thunderbird", "Mozilla Suite" as the application names in articles' titles and text. Don't use "Mozilla Firefox", "Mozilla Thunderbird", "Mozilla" (meaning the Suite), just "Suite" or "Seamonkey". Try to avoid "Mozilla Mail" when "Mozilla Suite" will suffice, especially in articles that also apply to Thunderbird.
* '''Application names.''' Use "Firefox" (but not "FireFox"), "Thunderbird", "Mozilla Suite" as the application names in articles' titles and text. Don't use "Mozilla Firefox", "Mozilla Thunderbird", "Mozilla" (meaning the Suite), just "Suite" or "Seamonkey". Try to avoid "Mozilla Mail" when "Mozilla Suite" will suffice, especially in articles that also apply to Thunderbird.
** Layout issues should use "Gecko" as the application name.
** Layout issues should use "Gecko" as the application name.
Line 20: Line 20:
** ''Mac OS''. Use ''Mac OS X'', not "Mac OSX", "MacOS X" or any other name.
** ''Mac OS''. Use ''Mac OS X'', not "Mac OSX", "MacOS X" or any other name.


* '''Common terms.''' Use these terms as listed here (sans quotes). Note the capital letters.
==Common terms==
** ''Good:'' "bookmark(s)", "cache", "Bookmarks Toolbar", "JavaScript", "Location Bar", "Profile Manager", "Search Bar", "Status Bar", "Junk Mail Controls"
Use these terms as listed here (sans quotes). Note the capital letters.
** ''Bad:'' "favorites", "Temporary Internet Files", "Links Toolbar", "Javascript", "address bar", "profile manager", "search box", "statusbar", "junk mail controls"
 
===General===
* ''Good:'' "JavaScript", "Profile Manager", "Status Bar"
* ''Bad:'' "Javascript", "profile manager", "statusbar"
 
===Browser===
* ''Good:'' "bookmark(s)", "cache", "Bookmarks Toolbar", "Location Bar", "Search Bar"
* ''Bad:'' "favorites", "Temporary Internet Files", "Links Toolbar", "address bar", "search box"
 
===Mail===
* ''Good:'' "Junk Mail Controls", "e-mail"
* ''Bad:'' "junk mail controls", "Email"


==Punctuation==
==Punctuation==

Revision as of 11:10, 29 March 2005


This is just going to be a list of stylistic writing suggestions that can make this entire KB more consistent in writing for now, in an informal bullet form. Feel free to add or delete any changes, since I border on grammar nazi. --hao2lian

Discuss these conventions on the discussion page! --Mozcerize

Articles that apply to more than one application

  • If the article applies to both the Mozilla Suite and Firefox/Thunderbird, create it and edit it for Mozilla Suite and Firefox/Thunderbird. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to Mozilla Suite too. This is a shame, because Mozilla Suite is in need of more people creating resources for it and converting old content to it.
  • Not every article that could be written to cover both the Mozilla Suite and Firefox/Thunderbird should be written this way. In some cases it might make the article excessively messy, especially if it refers to a series of steps or menu choices that differ in the Mozilla Suite and Firefox/Thunderbird (example). In such cases it's probably best not to write combined product articles. Use your best judgment.
  • If you're creating a new article and you're not sure if it applies to more than one application (e.g., you're writing a Firefox article but you're not an experienced Mozilla Suite user), go ahead and write it for just one product. Someone else can edit it later if needed.
  • As stated in the Rules, make sure to follow the new naming conventions for article titles that apply to more than one application.

Commonly used names

  • Application names. Use "Firefox" (but not "FireFox"), "Thunderbird", "Mozilla Suite" as the application names in articles' titles and text. Don't use "Mozilla Firefox", "Mozilla Thunderbird", "Mozilla" (meaning the Suite), just "Suite" or "Seamonkey". Try to avoid "Mozilla Mail" when "Mozilla Suite" will suffice, especially in articles that also apply to Thunderbird.
    • Layout issues should use "Gecko" as the application name.
  • OS names.
    • Windows. Use "Windows" when referring to the whole family of Microsoft Windows operation systems. For specific versions use: "Windows 95", "Windows 98", "Windows ME", "Windows NT", "Windows 2000", "Windows XP", "Windows XP SP2". When combining names, use forward slashes, e.g.: "Windows 2000/XP".
    • Linux. Use "Linux" when referring to *nix-like systems. Do not use "GNU/Linux" or any other name. If you absolutely need to use a name of a particular distribution, note your choice (along with the link to the article) in Talk:In-House Style.
    • Mac OS. Use Mac OS X, not "Mac OSX", "MacOS X" or any other name.

Common terms

Use these terms as listed here (sans quotes). Note the capital letters.

General

  • Good: "JavaScript", "Profile Manager", "Status Bar"
  • Bad: "Javascript", "profile manager", "statusbar"

Browser

  • Good: "bookmark(s)", "cache", "Bookmarks Toolbar", "Location Bar", "Search Bar"
  • Bad: "favorites", "Temporary Internet Files", "Links Toolbar", "address bar", "search box"

Mail

  • Good: "Junk Mail Controls", "e-mail"
  • Bad: "junk mail controls", "Email"

Punctuation

  • Use "arrows" to denote menu order (e.g. "Tools -> Options"), and place a space either side of the arrow to facilitate line breaks.
  • Put menu hierarchy, keyboard shortcuts, and file names into quotation marks (e.g. "Tools -> Options", "Ctrl+PageDown", "compreg.dat").
  • Just a personal pet peeve: use the dash and hyphen correctly [1] [2]. [When using dashes and hyphens, you should not include white space around them. For example, use “9–16” and “Firefox—and Mozilla—can be used” which are achieved using “9–16” and “Firefox—and”. --Mozcerize]
  • When discussing keyboard and mouse actions: left-click, right-click etc. are hyphenated and uncapitalized; Shift, Ctrl, Alt etc. have their first letter capitalized (and only their first letter); key combinations are written using "+" so that "hold down Ctrl and press 'D'" should be written "Ctrl+D".

Style

  • Use bolding and italics only when absolutely necessary.
  • Don't start too many small, idiosyncratic paragraphs. If paragraphs are a couple of sentences that last about two lines, try and see if you can combine them into one paragraph.