In-house style: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
m (also link to rules)
Line 11: Line 11:
==Commonly used names==
==Commonly used names==
* '''Application names''':  
* '''Application names''':  
** Use "Firefox" (but not "FireFox"), "Thunderbird", and "Mozilla Suite" as the application names in articles' titles and text. Don't use "Mozilla Firefox", "Mozilla Thunderbird", "Mozilla" (meaning the Suite), "Mozilla Application Suite", just "Suite" or "Seamonkey". Try to avoid "Mozilla Mail" when "Mozilla Suite" will suffice, especially in articles that also apply to Thunderbird.
** '''Use''' "Firefox" (but not "FireFox"), "Thunderbird", and "[the] Mozilla Suite" as the application names in articles' titles and text. '''Don't use''' "Mozilla Firefox", "Mozilla Thunderbird", "Mozilla" (meaning the Suite), "[the] Mozilla Application Suite", "[the] Suite" or "Seamonkey". Try to avoid "Mozilla Mail" when "[the] 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.



Revision as of 13:41, 17 April 2005

Adhering to the in-house style when editing articles helps to keep the Knowledge Base looking consistent and professional.

Be sure to also read the rules. If you create new articles as well as edit existing ones then please read and follow the article naming conventions.

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, if you can. 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.

Commonly used names

  • Application names:
    • Use "Firefox" (but not "FireFox"), "Thunderbird", and "[the] Mozilla Suite" as the application names in articles' titles and text. Don't use "Mozilla Firefox", "Mozilla Thunderbird", "Mozilla" (meaning the Suite), "[the] Mozilla Application Suite", "[the] Suite" or "Seamonkey". Try to avoid "Mozilla Mail" when "[the] 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). Terms like "Profile Manager" and "Bookmarks Toolbar" refer to named product features and function as proper nouns. Note the capital letters.

  • General:
    • Good: "JavaScript", "Profile Manager", "Status Bar"
    • Bad: "Javascript", "profile manager", "statusbar"
  • Browser-related:
    • Good: "bookmark(s)", "Bookmarks Toolbar", "cache", "Location Bar", "plugin", "Search Bar"
    • Bad: "favorites", "Links Toolbar", "Temporary Internet Files", "address bar", "plug-in", "search box"
  • Mail-related:
    • Good: "e-mail", "Junk Mail Controls", "Local Folders"
    • Bad: "Email", "junk mail controls", "local folders"

Special punctuation and formatting

  • Menu order: Use "arrows" to denote menu order (e.g. "Tools -> Options"), and place a space either side of the arrow to facilitate line breaks. Use quotation marks around the whole menu sequence.
  • 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".
  • Keyboard shortcuts: Put quotation marks around keyboard shortcuts (e.g., "Ctrl+PageDown")
  • Path names: Enclose these in <tt> tags so that they will appear in a monospace font (e.g., C:\Program Files\Mozilla Firefox\firefox.exe). Folders whose location varies (e.g., "profile folder" and "install folder") can be enclosed in angle brackets when part of a path (e.g., <profile folder>/chrome/overlayinfo/).
  • Directory & file names: Put these in quotation marks when they are used in a sentence but are not connected to a longer pathname (e.g., "Go to the "chrome" folder in your profile folder and find the "userChrome.css" file").
  • Mail folders (as listed in the folders pane): Write these as simply Inbox, Sent, Junk, Trash, etc., without italics or quotation marks; the corresponding files for each, like all other files, should be written in quotation marks (e.g., "Inbox", "Sent", "Junk", "Trash", etc.).

Other style considerations, pet peeves, etc.

  • Don't start too many small, idiosyncratic paragraphs. If several paragraphs each consist of a couple of sentences with only a few lines length, try to combine them into a single paragraph.
  • Use bolding and italics only when absolutely necessary.
  • Don't overdo linking. Since links stand out visually, they can disrupt the reader's flow and become a distraction rather than an aid. Try not to put the same link more than once in a single logical unit of an article (e.g., a section of a tutorial). For example, if you mention "profile folder" several times, link only the first one, or the one that's relating to something technical, at a point where the reader might logically want to read up on the specifics.
  • Headers/subheaders within articles should be capitalized in the same way as article titles.
  • 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&ndash;16” and “Firefox&mdash;and”. --Mozcerize]
  • "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup.