In-house style: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
(About tables.)
 
(29 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{org}}
{{org}}
Adhering to the in-house style when editing articles helps to keep the Knowledge Base looking consistent and professional.
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]].  
 
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 ([[Thunderbird : FAQs : Multiple SMTP Servers |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==
==Commonly used names==
* '''Application 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.
** '''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.
** Layout issues should use "Gecko" as the application name.


Line 17: Line 10:
** ''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".
** ''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]].
** ''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.
** ''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==
==Common terms==
Line 33: Line 26:
** ''Good:'' "e-mail", "Junk Mail Controls", "Local Folders"
** ''Good:'' "e-mail", "Junk Mail Controls", "Local Folders"
** ''Bad:'' "Email", "junk mail controls", "local folders"
** ''Bad:'' "Email", "junk mail controls", "local folders"
==Markup language==
The wiki software supports both [http://en.wikipedia.org/wiki/Wiki_markup WikiText] (the wiki markup language) and [http://en.wikipedia.org/wiki/Html 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'', <u>underlining</u>, <tt>typewriter font</tt>, 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==
==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.
 
* '''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., "[[Menu differences in Windows, Linux, and Mac|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 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")
* '''Keyboard shortcuts''': Put quotation marks around keyboard shortcuts (e.g., "Ctrl+PageDown")
* '''Path names''': Enclose these in <nowiki><tt></nowiki> tags so that they will appear in a monospace font (e.g., <tt>C:\Program Files\Mozilla Firefox\firefox.exe</tt>). Folders whose location varies (e.g., "profile folder" and "install folder") can be enclosed in angle brackets when part of a path (e.g., <tt><profile folder>/chrome/overlayinfo/</tt>).
* '''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''': 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 <nowiki><tt></nowiki> instead).
*'''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. 
* '''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.).
*'''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.")  
* '''Tables''': You should use [http://meta.wikimedia.org/wiki/Help:Table Mediawiki-syntax tables] for tables. You should also use the <code><nowiki>{{prettytable}}</nowiki></code> template (see [[Template:Prettytable]]). The template is a modified version of [http://meta.wikimedia.org/wiki/Template:Prettytable meta.wikipedia.org's]. [[Product comparison matrix | For example]],
* '''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 and values, directory and file names or command line argument phrases, when included as separate entries in a table cell, code box, or list. Monospace font (<nowiki><tt></tt></nowiki> tags) used to be used with path / folder / file names - it is no longer used for anything.
 
==Tables==
Use [http://meta.wikimedia.org/wiki/Help:Table Mediawiki-syntax tables] for tables, together with the <code><nowiki>{{prettytable}}</nowiki></code> template (see [[Template:Prettytable]]). The template is a modified version of [http://meta.wikimedia.org/wiki/Template:Prettytable meta.wikipedia.org's]. [[Product comparison matrix | For example]],
  <nowiki>{| {{prettytable}}</nowiki>
  <nowiki>{| {{prettytable}}</nowiki>
  ! Odds || Evens
  ! || Odds || Evens
  |-
  |-
  ! Row 1 || 1 || 2
  ! Row 1  
| 1 || 2
  |-
  |-
  ! Row 2 || 3 || 4
  ! Row 2
| 3 || 4
  |-
  |-
  ! Row 3 || 5 || 6
  ! Row 3
| 5 || 6
  <nowiki>|}</nowiki><br>
  <nowiki>|}</nowiki><br>
<br>
 
This produces<br>
This produces<br>
{| {{prettytable}}
{| {{prettytable}}
! Odds || Evens
! || Odds || Evens
|-
|-
! Row 1 || 1 || 2
! Row 1  
| 1 || 2
|-
|-
! Row 2 || 3 || 4
! Row 2
| 3 || 4
|-
|-
! Row 3 || 5 || 6
! Row 3
| 5 || 6
|}
|}


==Other style considerations, pet peeves, etc.==
==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 <nowiki>{{cleanup}}</nowiki> at the top of the article. This will expand to the message shown [[Template:Cleanup | 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.
* 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.
* 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.
* 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><nowiki></nowiki> tag, like this: <nowiki><nowiki>http://www.example.com</nowiki></nowiki>
* Headers/subheaders within articles should be capitalized in the same way as [[Article naming conventions|article titles]].
* Headers/subheaders within articles should be capitalized in the same way as [[Article naming conventions |article titles]]. In other words, ''do not capitalize'' the first letter of each main word unless referring to product names or named product features and functions used as proper nouns ([[#Common terms|see above]]).  Punctuation marks or symbols should be similarly avoided.  
* Use <nowiki>==See also==</nowiki> when linking to articles on the KB. Use <nowiki>==External links==</nowiki> to link to web pages outside of the KB. As per Wikipedia style.
* Use <nowiki>==See also==</nowiki> when linking to other MozillaZine KB articles. Use <nowiki>==External links==</nowiki> to link to web pages outside of the Knowledge Base.  
* Use the dash and hyphen correctly [http://en.wikipedia.org/wiki/Dash] [http://en.wikipedia.org/wiki/Hyphen]. [When using dashes and hyphens, you should not include white space around them. For example, use &ldquo;9&ndash;16&rdquo; and &ldquo;Firefox&mdash;and Mozilla&mdash;can be used&rdquo; which are achieved using &ldquo;9&amp;ndash;16&rdquo; and &ldquo;Firefox&amp;mdash;and&rdquo;. --Mozcerize]
* Use the dash and hyphen correctly [http://en.wikipedia.org/wiki/Dash] [http://en.wikipedia.org/wiki/Hyphen]. When using dashes and hyphens, you should not include white space around them. For example, use &ldquo;9&ndash;16&rdquo; and &ldquo;Firefox&mdash;and Mozilla&mdash;can be used&rdquo; which are achieved using &ldquo;9&amp;ndash;16&rdquo; and &ldquo;Firefox&amp;mdash;and&rdquo;.
* "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup.
* "Backup" is a noun; "back up" is the verb. When you back up your mail, you're making a backup. The same is true of ''the login/logout'' and ''to log in/out''.
* The spelling ''it's'' means only ''it is'', never ''of it'' (spelled ''its''). Similarly ''you're'' (you are) vs. ''your'' (of you), ''they're'' (they are) vs. ''their'' (of them) vs. ''there'' (at that place, or pron. [ðər] in ''there is'' etc.).
* Don't capitalize entire words.
 
==See also==
* [[MozillaZine Knowledge Base:Formatting]]
*  [[Rules and guidelines]]

Latest revision as of 17:36, 30 August 2010

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 and values, directory and file names or command line argument phrases, when included as separate entries in a table cell, code box, or list. Monospace font (<tt></tt> tags) used to be used with path / folder / file names - it is no longer used for anything.

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. In other words, do not capitalize the first letter of each main word unless referring to product names or named product features and functions used as proper nouns (see above). Punctuation marks or symbols should be similarly avoided.
  • Use ==See also== when linking to other MozillaZine KB articles. 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. The same is true of the login/logout and to log in/out.
  • The spelling it's means only it is, never of it (spelled its). Similarly you're (you are) vs. your (of you), they're (they are) vs. their (of them) vs. there (at that place, or pron. [ðər] in there is etc.).
  • Don't capitalize entire words.

See also