In-house style

From MozillaZine Knowledge Base
Revision as of 15:46, 19 February 2008 by Alice Wyman (talk | contribs) (→‎Special punctuation and formatting: fixed errant formatting.)
Jump to navigationJump to search

This page explains the style guidelines that we try to follow when creating or 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 to add your contributions 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.

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 an HTML expert don't use that as an excuse, most articles don't need advanced features.

Coloring should not be used in an 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. Bold, italics, underlining, typewriter font, etc., and any combination of them, are almost more than enough.

Either WikiText or HTML, or even color, 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: Put folder and file path names in italics when they are used within a sentence (e.g., "Delete the C:\Program Files\Mozilla Firefox\plugins\npmozax.dll file"). Folders whose location varies (e.g., "profile folder" and "installation directory") can be enclosed in angle brackets when part of a path (e.g., "Open the <profile folder>\bookmarkbackups\ folder.")
  • Directory & file names: Put these in quotation marks when they are used in a sentence but are not connected to a longer path name (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 for file names that are article links.
  • Path or file names followed by command line arguments: Place the entire phrase in italics when used within a sentence (e.g., "Go to the Start menu, open the Run dialog, type in firefox.exe -profilemanager and click OK.")
  • Mail folders (as listed in the folders pane): Write these simply as 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.).
  • Preference names and values: Put these in bold text when they are used in a sentence (e.g., "Use about:config to set the network.cookie.cookieBehavior preference to 1.") Exceptions: No special formatting is required for preference names that link to articles.

Note: No special punctuation or formatting is required for path names, preference names, directory and file names or command line argument phrases, when included as separate entries in a table cell, code box, or list.

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