In-house style

From MozillaZine Knowledge Base
Revision as of 09:02, 14 January 2008 by Tanstaafl (talk | contribs) (added Markup language section)
Jump to navigationJump to search

This page explains the style guidelines that we try to follow when editing articles to help keep the Knowledge Base looking consistent and professional. If you're a newcomer to the Knowledge Base, don't feel that you need to master everything listed below before you can create a new article or contribute to an existing one. The most important thing is for you to add your contribution to the Knowledge Base; someone else can tidy it up later, if needed. If you plan to create a new article, please read and follow the article naming conventions.

Articles that apply to more than one application

  • If the article applies to both Mozilla Suite/SeaMonkey and Firefox or Thunderbird, create it and edit it to include SeaMonkey also, if you can. A lot of articles written talk exclusively about Firefox or Thunderbird, yet they often apply to SeaMonkey. This is a shame, because SeaMonkey 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 SeaMonkey and Firefox or 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 SeaMonkey and Firefox or 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 SeaMonkey 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 "SeaMonkey" as the application names in articles' titles. In article text, avoid using "Mozilla Firefox" or "Mozilla Thunderbird". Try to avoid using "SeaMonkey Mail" when "SeaMonkey" 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. Use "Mac OS X", not "Mac OSX", "MacOS X" "OSX" or any other name, when referring to the Apple Mac OS X operating system.

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"

Markup language

The wiki software supports both WikiText (the wiki markup language) and HTML. Use WikiText whenever possible in articles. The use of HTML in articles is discouraged - it should only be used when you can't obtain the same result using WikiText, and should never be used for color. If you are a HTML expert don't use that as an excuse, most articles don't need advanced features.

Coloring should not be used in a article. Any colors should be a normal part of a screen shot, icon, or image added to the article for informational purposes - not for highlighting or formatting.

Either WikiText or HTML can be used in a user page.

Special punctuation and formatting

  • Menu sequences: 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. In cases where menu sequences differ by OS, it may be helpful to include a link to Menu differences in Windows, Linux, and Mac within the menu sequence itself (e.g., "Tools -> Options -> Advanced").
  • 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 "installation directory") can be enclosed in angle brackets when part of a path (e.g., <profile folder>/chrome/overlayinfo/).
  • Directory & file names: In general, 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"). Exceptions: you can omit the quotation marks around well-known file names (e.g., prefs.js or user.js), second and subsequent instances of a file name that appears multiple times in the same article, or file names used in Dev articles (you can use <tt> instead).
  • 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 should be treated like other file names and normally be written in quotation marks (e.g., "Inbox", "Sent", "Junk", "Trash", etc.).

Removing obsolete information

Information on older versions should be removed after two major releases, if its long or distracting and of little use. For example, Thunderbird 2 and Thunderbird 1.5 are the most recent major releases so, for Thunderbird, anything before 1.5 is fair game. However, comments such as "Applies to Firefox since release 0.9" in about:config articles is a good example of information that shouldn't be removed. Its very short, and the historical perspective can be useful.

Tables

Use Mediawiki-syntax tables for tables, together with the {{prettytable}} template (see Template:Prettytable). The template is a modified version of meta.wikipedia.org's. For example,

{| {{prettytable}}
! || Odds || Evens
|-
! Row 1 
| 1 || 2
|-
! Row 2
| 3 || 4
|-
! Row 3
| 5 || 6
|}

This produces

Odds Evens
Row 1 1 2
Row 2 3 4
Row 3 5 6

Templates

There are numerous templates available to insert standardized content and/or formatting into pages. For instance, if you come across an article that needs a formatting makeover in order to follow the style guidelines listed on this page, you can insert {{cleanup}} at the top of the article. This will expand to the message shown here.

For a list of useful templates and further explanation, see Rules/Templates.

Other style considerations

  • 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. If you don't want a link to be clickable, use the <nowiki> tag, like this: <nowiki>http://www.example.com</nowiki>
  • Headers/subheaders within articles should be capitalized in the same way as article titles and punctuation marks or symbols should be similarly avoided.
  • Use ==See also== when linking to articles on the KB. Use ==External links== to link to web pages outside of the Knowledge Base.
  • 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”.
  • "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup.
  • Don't capitalize entire words.

See also