MDN Style Guide

  • Revision slug: Project:MDC_style_guide
  • Revision title: MDN Style Guide
  • Revision id: 340493
  • Created:
  • Creator: madarche
  • Is current revision? No
  • Comment Fixed the "images" section id

Revision Content

{{ MDCProjectPagesTOC() }}

In an effort to display documentation in an organized, standardized and easy-to-read manner, the Mozilla Developer Network style guide describes how text should be organized, spelled, formatted, and so on. These are guidelines rather than strict rules. We are more interested in content than formatting, so don't feel obligated to learn the style guide before contributing. Do not be upset or surprised, however, if an industrious volunteer later edits your work to conform to this guide.

This language aspects of this guide apply primarily to English-language documentation. Other languages may have (and are welcome to create) their own style guides.

For style standards that apply to non-technical writing, refer to the One Mozilla style guide.

Basics

Page names

Page names are used in search results and also used to structure the page hierarchy in the breadcrumb list at the top of the page. The page name (which is displayed at the top of the page and in the search results) can be different from the page "slug" (which is used to build the page URL).

Page and heading capitalization

Page names and section headings should use sentence-style capitalization (only capitalize the first word and proper nouns) rather than headline-style capitalization:

  • Correct: "A new method for creating JavaScript rollovers"
  • Incorrect: "A New Method for Creating JavaScript Rollovers"
The capitalization rules for page names apply to new pages. Many pages in this wiki don't conform to these rules. You can fix these exceptions as you are editing pages for other reasons but please don't edit a page for the sole purpose of fixing the page name's capitalization.

Unique page names

Wherever possible, pages should have a unique title. If the page topic is a common word like "Optimization", use an additional word that provides context, for example "Optimizing lists" or "CSS Optimization". If there are two or more pages which have the same "natural" title, a disambiguation page should be created.

Multi-page articles

If the content you are adding to the wiki requires multiple pages, use the following page naming method. This enables the wiki to build the breadcrumb list at the top of the page correctly.

If you don't use the pathname-like hierarchy depicted here, your articles will all be located at the top of the hierarchy instead of nested.

Sections, paragraphs, and newlines

Use heading levels in decreasing order: {{ HTMLElement("h2") }} then {{ HTMLElement("h3") }} then {{ HTMLElement("h4") }}, without skipping levels. H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers you should consider breaking up the article into several smaller articles which are linked manually.

The enter (or return) key on your keyboard starts a new paragraph. To insert a newline without a space, hold down the shift key while pressing enter.

Text formatting and styles

Use the "Formatting Styles" drop-down list to apply predefined styles to selected content.

Note: The "Note" style is used to call out important notes, like this one.
Warning: Similarly, the "Warning" style creates warning boxes like this.

Code formatting

Tabs and line breaks

Use two spaces per tab in all code samples. Code should be indented cleanly. For example:

if (condition) {
  /* handle the condition */
} else {
  /* handle the "else" case */
} 

Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break at natural breaking points. Some examples follow:

if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
      || class.YET_ANOTHER_CONDITION ) {
  /* something */
}

var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
                           .createInstance(Components.interfaces.nsIToolkitProfileService);

Formatting

Use the "Code" button (labelled with two angle brackets "<>") to apply inline code-style formatting to function names, variable names, and method names. For example, "the frenchText() function".

Method names should be followed by a pair of parentheses: doSomethingUseful().

Syntax highlighting

Entire lines (or multiple lines) of code should be formatted via syntax highlighting. Select the text, then select the appropriate language from the "Syntax Highlighter" drop-down list. The following example shows text with JavaScript formatting:

for (var i = 0, j = 9; i <= 9; i++, j--)
  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);

If no appropriate transformation is available, use the pre tag.

x = 42;

Formatting HTML Elements

Element names
Use the HTMLElement template, (e.g., {{HTMLElement("title")}}), which creates a link to the page for that element. If you don't want to create a link, enclose the name in angle brackets and use "Code (inline)" style (e.g., <title>).
Attribute names
Use bold face.
Attribute definitions
Use the htmlattrdef template (e.g., {{htmlattrdef("type")}}) for the definition term, so that it can be linked to from other pages. (Use the htmlattrxref template (e.g., {{htmlattrxref("attr","element")}}) to reference attribute definitions.)
Attribute values
Use "Code (inline)" style, and do not use quotation marks around strings, unless needed by the syntax of a code sample. E.g.: When the type attribute of an <input> element is set to email or tel ...
Labeling attributes
Use labels like {{ HTMLVersionInline(5) }} thoughtfully. For example, use them next to the bold attribute name but not for every occurrence in your body text.

Force ignore of wiki markup

If you need a particular piece of wiki markup to be ignored by the parser, simply use the "plain" CSS class, like this:

<span class="plain">'''this wiki markup will not be interpreted'''</span>

'''this wiki markup will not be interpreted'''

Latin abbreviations

In notes and parentheses

  • Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and in notes. Use periods in these abbreviations.
    • Correct: Web browsers (e.g. Firefox) can be used ...
    • Incorrect: Web browsers e.g. Firefox can be used ...
    • Incorrect: Web browsers, e.g. Firefox, can be used ...
    • Incorrect: Web browsers, (eg: Firefox) can be used ...

In running text

  • In regular text (i.e. text outside of notes or parentheses), use the English equivalent of the abbreviation.
    • Correct: ... web browsers, and so on.
    • Incorrect: ... web browsers, etc.
    • Correct: Web browsers such as Firefox can be used ...
    • Incorrect: Web browsers e.g. Firefox can be used ...

Meanings and English equivalents of Latin abbreviations

Abbrev Latin English
cf. confer compare
e.g. exempli gratia for example
et al. et alii and others
etc. et cetera and so forth, and so on
i.e. id est that is, in other words
N.B. nota bene note well
P.S. post scriptum postscript

N.B. Be careful not to confuse "e.g." with "i.e."

Acronyms and abbreviations

Capitalization and periods

Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".

  • Correct: XUL
  • Incorrect: X.U.L.; Xul

Expansion

On the first mention of a term on a page, expand acronyms likely to be unfamiliar to users. When in doubt, expand it, or, better, link it to the article describing the technology.

  • Correct: "XUL (XML User Interface Language) is Mozilla's XML-based language..."
  • Incorrect: "XUL is Mozilla's XML-based language..."

Plurals of acronyms and abbreviations

For plurals of acronyms or abbreviations, add s.

  • Correct: CD-ROMs
  • Incorrect: CD-ROM's

Contractions

Use contractions (e.g. "don't", "can't", "shouldn't") if you prefer.

Pluralization

Use English-style plurals, not the Latin- or Greek-influenced forms.

  • Correct: syllabuses, octopuses
  • Incorrect: syllabi, octopi

Hyphenation

Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.

  • Correct: email, re-elect, co-op
  • Incorrect: e-mail, reelect, coop

Numbers and numerals

Dates

For dates (not including dates in code samples) use the format "January 1, 1990".

  • Correct: February 24, 2006
  • Incorrect: February 24th, 2006; 24 February, 2006; 24/02/2006

Alternately, you can use the YYYY/MM/DD format.

  • Correct: 2006/02/24
  • Incorrect: 02/24/2006; 24/02/2006; 02/24/06

Decades

For decades, use the format "1990s".

  • Correct: 1990s
  • Incorrect: 1990's

Plurals of numerals

For plurals of numerals add "s".

  • Correct: 486s
  • Incorrect: 486's

Commas

In running text, use commas only in five-digit and larger numbers.

  • Correct: 4000; 54,000
  • Incorrect: 4,000; 54000

Punctuation

Serial comma

Use the serial comma. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.

  • Correct: I will travel on trains, planes, and automobiles.
  • Incorrect: I will travel on trains, planes and automobiles.

Spelling

For words with variant spellings, always use the first entry at Answers.com. Do not use variant spellings.

  • Correct: localize, honor
  • Incorrect: localise, honour

Wiki markup and usage

Signing edits

Enter three tildes in a row to insert your username with a link to your user page.  Enter four tildes in a row to insert your username as well as the date and time of your edit. This is particularly helpful on Talk pages. For example:

Sheppy (three tildes)

and

Sheppy 19 Aug 2008 (four tildes)

To automatically create a link to a Bugzilla bug, use this template:

\{{Bug(322603)}}

This results in:

{{ Bug(322603) }}

For WebKit bugs, you can use this template:

\{{Webkitbug("322603")}}

This results in:

{{ Webkitbug("322603") }}

Tags

Tags provide meta information about a page and / or indicate that a page needs work or is deprecated. Every page in the wiki should be tagged. To add tags, simply click "Add and edit tags" in the tag list at the end of the article. Tags will autocomplete as you type. Each article may have as many tags as appropriate. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.

Tagging pages that need work

Some of the most common editing tags we use are:

  • NeedsMarkupWork: the formatting is not standard or not consistent with other pages.
  • NeedsExample: needs one or more illustrative code examples of the item documented.
  • NeedsContent: the item is incomplete and needs to be filled out.
  • NeedsJSVersion: needs information about the version of JavaScript and EcmaScript this item first appears in.
  • NeedsBrowserCompatibility: needs a browser compatibility table or needs the table filled out.
  • MakeBrowserAgnostic: the article is written with a focus on Gecko, when it is actually about a standard function or feature, which should be rewritten to be generic.

Tagging obsolete pages

Use the following tags for pages that are not current:

  • Junk: Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.
  • Obsolete: Use for content that is technically superceded, but still valid in context. For example an HTML element that is obsolete in HTML5 is still valid in HTML 4.01. You can also use the {{obsolete_header()}} template to put a prominent banner on the topic.
  • Archive: Use for content that is technically superceded and no longer useful. If possible, add a note to the topic referring readers to a more current topic. For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the NeedsUpdate tag, and add an explanation on the Talk page.) Pages with the Archive tag may eventually be moved into an archive sub-tree and/or hidden in search results.

Landing pages

Landing pages are pages at the root of a topic area of the site, such as the main CSS or HTML pages. They have a standard format that consists of three areas:

  1. A brief (typically one paragraph) overview of what the technology is and what it's used for. See {{anch("Writing a landing page overview")}} for tips.
  2. A two-column list of links with appropriate headings. See {{anch("Creating a page link list")}} for guidelines.
  3. An optional "Browser compatibility" section at the bottom of the page.

The link list section of an MDN landing page consists of two columns. These are created using the following HTML:

<div class="row topicpage-table">
  <div class="section">
    ... left column contents ...
  </div>
  <div class="section">
    ... right column contents ...
  </div>
</div>

The left-hand column should be a list of articles, with an <h2> header at the top of the left column explaining that it's a list of articles about the topic (for example "Documentation and tutorials about foo"); this header should use the CSS class "Documentation". Below that is a <dl> list of articles, with each article's link in a <dt> block and a brief one-or-two setence summary of the article in the corresponding <dd> block.

The right-hand column should contain one or more of the following sections, in order:

Getting help from the community
This should provide information on IRC channels and mailing lists available about the topic. The heading should use the class "Community".
Tools
A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".
Related topics
A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".

Using, inserting images

It's possible to have images in the articles you create or modify. It sometimes nice to have to have texts looks less uninviting, especially very technical ones.

The preferred way is the following:

  1. Attach the desired image file to the article (at the bottom of every article in edit mode)
  2. Create an image in the WYSIWYG editor
  3. In the WYSIWYG editor in the drop-down list listing attachments, select the newly created attachment which is your image
  4. Press OK, it's done

Other references

Preferred style guides

If you have questions about usage and style not covered here, I recommend referring to the Economist style guide or, failing that, the Chicago Manual of Style. The Yahoo Style Guide covers many topics that are specific to writing on and about the Web, and it keeps current with online usage. You should also read the MDN formatting guide, which offers insight into formatting and layout standards we use.

Preferred dictionary

For questions of spelling, please refer to Answers.com. The spell-checker for this site uses American English. Please do not use variant spellings (e.g., use honor rather than honour).

We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please send them to the MDC mailing list or project lead so we know what should be added.

MDC-specific

Language, grammar, spelling

If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.

Revision Source

<p>{{ MDCProjectPagesTOC() }}</p>
<p>In an effort to display documentation in an organized, standardized and easy-to-read manner, the Mozilla Developer Network style guide describes how text should be organized, spelled, formatted, and so on. These are guidelines rather than strict rules. We are more interested in content than formatting, so don't feel obligated to learn the style guide before contributing. Do not be upset or surprised, however, if an industrious volunteer later edits your work to conform to this guide.</p>
<p>This language aspects of this guide apply primarily to English-language documentation. Other languages may have (and are welcome to create) their own style guides.</p>
<p>For style standards that apply to non-technical writing, refer to the <a href="http://www.mozilla.org/en-US/styleguide/" title="http://www.mozilla.org/en-US/styleguide/">One Mozilla style guide</a>.</p>
<h2 id="Page_name_and_heading_capitalization" name="Page_name_and_heading_capitalization">Basics</h2>
<h3 id="Page_name_and_heading_capitalization" name="Page_name_and_heading_capitalization">Page names</h3>
<p>Page names are used in search results and also used to structure the page hierarchy in the breadcrumb list at the top of the page. The page name (which is displayed at the top of the page and in the search results) can be different from the page "slug" (which is used to build the page URL).</p>
<h4 id="Page_name_and_heading_capitalization" name="Page_name_and_heading_capitalization">Page and heading capitalization</h4>
<p>Page names and section headings should use sentence-style capitalization (only capitalize the first word and proper nouns) rather than headline-style capitalization:</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: "A new method for creating JavaScript rollovers"</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: "A New Method for Creating JavaScript Rollovers"</li>
</ul>
<div class="note">
  The capitalization rules for page names apply to new pages. Many pages in this wiki don't conform to these rules. You can fix these exceptions as you are editing pages for other reasons but please don't edit a page for the sole purpose of fixing the page name's capitalization.</div>
<h4 id="Sections.2C_Paragraphs.2C_Newlines" name="Sections.2C_Paragraphs.2C_Newlines">Unique page names</h4>
<p>Wherever possible, pages should have a unique title. If the page topic is a common word like "Optimization", use an additional word that provides context, for example "Optimizing lists" or "CSS Optimization". If there are two or more pages which have the same "natural" title, a <a href="/Project:en/Disambiguation" title="Project:en/Disambiguation">disambiguation page</a> should be created.</p>
<h4 id="Multi-page_articles">Multi-page articles</h4>
<p>If the content you are adding to the wiki requires multiple pages, use the following page naming method. This enables the wiki to build the breadcrumb list at the top of the page correctly.</p>
<ul>
  <li><a href="/en/Learning_JavaScript" title="en/Learning_JavaScript">Learning JavaScript</a> - Main table-of-contents page</li>
  <li><a href="/en/Learning_JavaScript/Introduction" title="en/Learning_JavaScript/Introduction">Learning JavaScript/Introduction</a></li>
  <li><a href="/en/Learning_JavaScript/A_layperson's_view" title="en/Learning_JavaScript/A_layperson's_view">Learning JavaScript/A layperson's view</a></li>
  <li><a href="/en/Learning_JavaScript/More_advanced_scripting" title="en/Learning_JavaScript/More_advanced_scripting">Learning JavaScript/More advanced scripting</a></li>
  <li><a href="/en/Learning_JavaScript/Next_steps" title="en/Learning_JavaScript/Next_steps">Learning JavaScript/Next steps</a></li>
</ul>
<p>If you don't use the pathname-like hierarchy depicted here, your articles will all be located at the top of the hierarchy instead of nested.</p>
<h3 id="Sections.2C_Paragraphs.2C_Newlines" name="Sections.2C_Paragraphs.2C_Newlines">Sections, paragraphs, and newlines</h3>
<p>Use heading levels in decreasing order: {{ HTMLElement("h2") }} then {{ HTMLElement("h3") }} then {{ HTMLElement("h4") }}, without skipping levels. H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers you should consider breaking up the article into several smaller articles which are linked manually.</p>
<p>The enter (or return) key on your keyboard starts a new paragraph. To insert a newline without a space, hold down the shift key while pressing enter.</p>
<h3 id="Text_Formatting" name="Text_Formatting">Text formatting and styles</h3>
<p>Use the "Formatting Styles" drop-down list to apply predefined styles to selected content.</p>
<div class="note">
  <strong>Note: </strong>The "Note" style is used to call out important notes, like this one.</div>
<div class="warning">
  <strong>Warning:</strong> Similarly, the "Warning" style creates warning boxes like this.</div>
<h3 id="Code_formatting">Code formatting</h3>
<h4 id="Tabs_and_line_breaks">Tabs and line breaks</h4>
<p>Use two spaces per tab in all code samples. Code should be indented cleanly. For example:</p>
<pre class="brush: js">
if (condition) {
&nbsp; /* handle the condition */
}&nbsp;else {
&nbsp; /* handle the "else" case */
} 
</pre>
<p>Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break at natural breaking points. Some examples follow:</p>
<pre class="brush: js">
if (class.CONDITION || class.OTHER_CONDITION&nbsp;||&nbsp;class.SOME_OTHER_CONDITION
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; || class.YET_ANOTHER_CONDITION )&nbsp;{
&nbsp; /*&nbsp;something */
}

var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
                           .createInstance(Components.interfaces.nsIToolkitProfileService);
</pre>
<h4 id="Formatting">Formatting</h4>
<p>Use the "Code" button (labelled with two angle brackets "&lt;&gt;") to apply inline code-style formatting to function names, variable names, and method names. For example, "the <code class="js plain">frenchText()</code> function".</p>
<p>Method names should be followed by a pair of parentheses:&nbsp;<code>doSomethingUseful()</code>.</p>
<h4 id="Syntax_highlighting">Syntax highlighting</h4>
<p>Entire lines (or multiple lines) of code should be formatted via syntax highlighting. Select the text, then select the appropriate language from the "Syntax Highlighter" drop-down list. The following example shows text with JavaScript formatting:</p>
<div class="line number2 index1 alt1">
  <pre class="brush: js">
for (var i = 0, j = 9; i &lt;= 9; i++, j--)
  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);</pre>
</div>
<p>If no appropriate transformation is available, use the <code>pre</code> tag.</p>
<pre>
x = 42;</pre>
<h4 id="Formatting_HTML.C2.A0Elements">Formatting HTML&nbsp;Elements</h4>
<dl>
  <dt>
    Element names</dt>
  <dd>
    Use the HTMLElement template, (e.g., <span class="nowiki">{{HTMLElement("title")}}</span>), which creates a link to the page for that element. If you don't want to create a link, enclose the name in angle brackets and use "Code (inline)" style (e.g., <code>&lt;title&gt;</code>).</dd>
  <dt>
    Attribute names</dt>
  <dd>
    Use <strong>bold face</strong>.</dd>
  <dt>
    Attribute definitions</dt>
  <dd>
    Use the htmlattrdef template (e.g., <span class="nowiki">{{htmlattrdef("type")}}</span>) for the definition term, so that it can be linked to from other pages. (Use the htmlattrxref template (e.g., <span class="nowiki">{{htmlattrxref("attr","element")}}</span>) to reference attribute definitions.)</dd>
  <dt>
    Attribute values</dt>
  <dd>
    Use "Code (inline)" style, and do not use quotation marks around strings, unless needed by the syntax of a code sample. E.g.:&nbsp;When the <strong>type</strong> attribute of an <code>&lt;input&gt;</code> element is set to <code>email</code> or <code>tel</code> ...</dd>
  <dt>
    Labeling attributes</dt>
  <dd>
    Use labels like {{ HTMLVersionInline(5) }} thoughtfully. For example, use them next to the bold attribute name but not for every occurrence in your body text.</dd>
</dl>
<h3 id="Force_ignore_of_wiki_markup">Force ignore of wiki markup</h3>
<p>If you need a particular piece of wiki markup to be ignored by the parser, simply use the "plain" CSS class, like this:</p>
<pre>
&lt;span class="plain"&gt;'''this wiki markup will not be interpreted'''&lt;/span&gt;
</pre>
<p><span class="nowiki">'''this wiki markup will not be interpreted'''</span></p>
<h3 id="Latin_abbreviations" name="Latin_abbreviations">Latin abbreviations</h3>
<h4 id="In_notes_and_parentheses" name="In_notes_and_parentheses">In notes and parentheses</h4>
<ul>
  <li>Common Latin abbreviations (etc., i.e., e.g.) may be used in parenthetical expressions and in notes. Use periods in these abbreviations.
    <ul>
      <li><span class="correct"><strong>Correct</strong></span>: Web browsers (e.g. Firefox) can be used ...</li>
      <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers e.g. Firefox can be used ...</li>
      <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers, e.g. Firefox, can be used ...</li>
      <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers, (eg: Firefox) can be used ...</li>
    </ul>
  </li>
</ul>
<h4 id="In_running_text" name="In_running_text">In running text</h4>
<ul>
  <li>In regular text (i.e. text outside of notes or parentheses), use the English equivalent of the abbreviation.
    <ul>
      <li><span class="correct"><strong>Correct</strong></span>: ... web browsers, and so on.</li>
      <li><span class="incorrect"><strong>Incorrect</strong></span>: ... web browsers, etc.</li>
      <li><span class="correct"><strong>Correct</strong></span>: Web browsers such as Firefox can be used ...</li>
      <li><span class="incorrect"><strong>Incorrect</strong></span>: Web browsers e.g. Firefox can be used ...</li>
    </ul>
  </li>
</ul>
<h4 id="Meanings_and_English_equivalents_of_Latin_abbreviations" name="Meanings_and_English_equivalents_of_Latin_abbreviations">Meanings and English equivalents of Latin abbreviations</h4>
<table class="fullwidth-table">
  <tbody>
    <tr>
      <th>Abbrev</th>
      <th>Latin</th>
      <th>English</th>
    </tr>
    <tr>
      <td>cf.</td>
      <td><em>confer</em></td>
      <td>compare</td>
    </tr>
    <tr>
      <td>e.g.</td>
      <td><em>exempli gratia</em></td>
      <td>for example</td>
    </tr>
    <tr>
      <td>et al.</td>
      <td><em>et alii</em></td>
      <td>and others</td>
    </tr>
    <tr>
      <td>etc.</td>
      <td><em>et cetera</em></td>
      <td>and so forth, and so on</td>
    </tr>
    <tr>
      <td>i.e.</td>
      <td><em>id est</em></td>
      <td>that is, in other words</td>
    </tr>
    <tr>
      <td>N.B.</td>
      <td><em>nota bene</em></td>
      <td>note well</td>
    </tr>
    <tr>
      <td>P.S.</td>
      <td><em>post scriptum</em></td>
      <td>postscript</td>
    </tr>
  </tbody>
</table>
<p>N.B. Be careful not to confuse "e.g." with "i.e."</p>
<h3 id="Acronyms_and_abbreviations" name="Acronyms_and_abbreviations">Acronyms and abbreviations</h3>
<h4 id="Capitalization_and_periods" name="Capitalization_and_periods">Capitalization and periods</h4>
<p>Use full capitals and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: XUL</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: X.U.L.; Xul</li>
</ul>
<h4 id="Expansion" name="Expansion">Expansion</h4>
<p>On the first mention of a term on a page, expand acronyms likely to be unfamiliar to users. When in doubt, expand it, or, better, link it to the article describing the technology.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: "XUL (XML User Interface Language) is Mozilla's XML-based language..."</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: "XUL is Mozilla's XML-based language..."</li>
</ul>
<h4 id="Plurals_of_acronyms_and_abbreviations" name="Plurals_of_acronyms_and_abbreviations">Plurals of acronyms and abbreviations</h4>
<p>For plurals of acronyms or abbreviations, add <em>s</em>.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: CD-ROMs</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: CD-ROM's</li>
</ul>
<h3 id="Contractions" name="Contractions">Contractions</h3>
<p>Use contractions (e.g. "don't", "can't", "shouldn't") if you prefer.</p>
<h3 id="Pluralization" name="Pluralization">Pluralization</h3>
<p>Use English-style plurals, not the Latin- or Greek-influenced forms.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: syllabuses, octopuses</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: syllabi, octopi</li>
</ul>
<h3 id="Hyphenation" name="Hyphenation">Hyphenation</h3>
<p>Hyphenate compounds when the last letter of the prefix is a vowel and is the same as the first letter of the root.</p>
<ul>
  <li><font color="green"><strong>Correct</strong></font>: email, re-elect, co-op</li>
  <li><font color="red"><strong>Incorrect</strong></font>: e-mail, reelect, coop</li>
</ul>
<h3 id="Numbers_and_numerals" name="Numbers_and_numerals">Numbers and numerals</h3>
<h4 id="Dates">Dates</h4>
<p>For dates (not including dates in code samples) use the format "January 1, 1990".</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: February 24, 2006</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: February 24th, 2006; 24 February, 2006; 24/02/2006</li>
</ul>
<p>Alternately, you can use the YYYY/MM/DD format.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: 2006/02/24</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: 02/24/2006; 24/02/2006; 02/24/06</li>
</ul>
<h4 id="Decades" name="Decades">Decades</h4>
<p>For decades, use the format "1990s".</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: 1990s</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: 1990's</li>
</ul>
<h4 id="Plurals_of_numerals" name="Plurals_of_numerals">Plurals of numerals</h4>
<p>For plurals of numerals add <em>"s"</em>.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: 486s</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: 486's</li>
</ul>
<h4 id="Commas" name="Commas">Commas</h4>
<p>In running text, use commas only in five-digit and larger numbers.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: 4000; 54,000</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: 4,000; 54000</li>
</ul>
<h3 id="Punctuation" name="Punctuation">Punctuation</h3>
<h4 id="Serial_comma" name="Serial_comma">Serial comma</h4>
<p>Use the serial comma. The serial (also known as "Oxford") comma is the comma that appears before the conjunction in a series of three or more items.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: I will travel on trains, planes, and automobiles.</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: I will travel on trains, planes and automobiles.</li>
</ul>
<h3 id="Spelling" name="Spelling">Spelling</h3>
<p>For words with variant spellings, always use the first entry at <a class="external" href="http://www.answers.com/library/Dictionary">Answers.com</a>. Do not use variant spellings.</p>
<ul>
  <li><span class="correct"><strong>Correct</strong></span>: localize, honor</li>
  <li><span class="incorrect"><strong>Incorrect</strong></span>: localise, honour</li>
</ul>
<h2 id="Wiki_markup_and_usage">Wiki markup and usage</h2>
<h3 id="Signing_edits">Signing edits</h3>
<p>Enter three tildes in a row to insert your username with a link to your user page.&nbsp; Enter four tildes in a row to insert your username as well as the date and time of your edit. This is particularly helpful on Talk pages. For example:</p>
<p><a class="internal" href="/User:Sheppy" title="User:Sheppy">Sheppy</a> (three tildes)</p>
<p>and</p>
<p><a class="internal" href="/User:Sheppy" title="User:Sheppy">Sheppy</a> 19 Aug 2008 (four tildes)</p>
<h3 id="External_links">External links</h3>
<p>To automatically create a link to a Bugzilla bug, use this template:</p>
<pre>
\{{Bug(322603)}}
</pre>
<p>This results in:</p>
<p>{{ Bug(322603) }}</p>
<p>For WebKit bugs, you can use this template:</p>
<pre>
\{{Webkitbug("322603")}}
</pre>
<p>This results in:</p>
<p>{{ Webkitbug("322603") }}</p>
<h3 id="Tags">Tags</h3>
<p>Tags provide meta information about a page and / or indicate that a page needs work or is deprecated. Every page in the wiki should be tagged. To add tags, simply click "Add and edit tags" in the tag list at the end of the article. Tags will autocomplete as you type. Each article may have as many tags as appropriate. For example, an article about using JavaScript in AJAX programming might have both "JavaScript" and "AJAX" as tags.</p>
<h4 id="Tagging_pages_that_need_work">Tagging pages that need work</h4>
<p>Some of the most common editing tags we use are:</p>
<ul>
  <li><strong>NeedsMarkupWork</strong>: the formatting is not standard or not consistent with other pages.</li>
  <li><strong>NeedsExample</strong>: needs one or more illustrative code examples of the item documented.</li>
  <li><strong>NeedsContent</strong>: the item is incomplete and needs to be filled out.</li>
  <li><strong>NeedsJSVersion</strong>: needs information about the version of JavaScript and EcmaScript this item first appears in.</li>
  <li><strong>NeedsBrowserCompatibility</strong>: needs a browser compatibility table or needs the table filled out.</li>
  <li><strong>MakeBrowserAgnostic</strong>: the article is written with a focus on Gecko, when it is actually about a standard function or feature, which should be rewritten to be generic.</li>
</ul>
<h4 id="Tagging_obsolete_pages">Tagging obsolete pages</h4>
<p>Use the following tags for pages that are not current:</p>
<ul>
  <li><em>Junk</em>: Use for spam, pages created by mistake, or content that is so bad that it should be deleted. Pages with this tag are deleted from time to time.</li>
  <li><em>Obsolete</em>: Use for content that is technically superceded, but still valid in context. For example an HTML element that is obsolete in HTML5 is still valid in HTML 4.01. You can also use the <span class="nowiki">{{obsolete_header()}}</span> template to put a prominent banner on the topic.</li>
  <li><em>Archive</em>: Use for content that is technically superceded and no longer useful. If possible, add a note to the topic referring readers to a more current topic. For example, a page that describes how to use the Mozilla CVS repository should refer readers to a current topic on using Mercurial repos. (If no corresponding current topic exists, use the <em>NeedsUpdate</em> tag, and add an explanation on the Talk page.) Pages with the Archive tag may eventually be moved into an archive sub-tree and/or hidden in search results.</li>
</ul>
<h3 id="Landing_pages">Landing pages</h3>
<p><strong>Landing pages</strong> are pages at the root of a topic area of the site, such as the main <a href="/en-US/docs/CSS" title="/en-US/docs/CSS">CSS</a> or <a href="/en-US/docs/HTML" title="/en-US/docs/HTML">HTML</a> pages. They have a standard format that consists of three areas:</p>
<ol>
  <li>A brief (typically one paragraph) overview of what the technology is and what it's used for. See {{anch("Writing a landing page overview")}} for tips.</li>
  <li>A two-column list of links with appropriate headings. See {{anch("Creating a page link list")}} for guidelines.</li>
  <li>An <strong>optional</strong> "Browser compatibility" section at the bottom of the page.</li>
</ol>
<h4 id="Creating_a_page_link_list">Creating a page link list</h4>
<p>The link list section of an MDN landing page consists of two columns. These are created using the following HTML:</p>
<pre class="brush: html">
&lt;div class="row topicpage-table"&gt;
  &lt;div class="section"&gt;
    ... left column contents ...
  &lt;/div&gt;
  &lt;div class="section"&gt;
    ... right column contents ...
  &lt;/div&gt;
&lt;/div&gt;</pre>
<p>The left-hand column should be a list of articles, with an <code>&lt;h2&gt;</code> header at the top of the left column explaining that it's a list of articles about the topic (for example "Documentation and tutorials about foo"); this header should use the CSS class "Documentation". Below that is a <code>&lt;dl&gt;</code> list of articles, with each article's link in a <code>&lt;dt&gt;</code> block and a brief one-or-two setence summary of the article in the corresponding <code>&lt;dd&gt;</code> block.</p>
<p>The right-hand column should contain one or more of the following sections, in order:</p>
<dl>
  <dt>
    Getting help from the community</dt>
  <dd>
    This should provide information on IRC channels and mailing lists available about the topic. The heading should use the class "Community".</dd>
  <dt>
    Tools</dt>
  <dd>
    A list of tools the user can look at to help with the use of the technology described in this section of MDN. The heading should use the class "Tools".</dd>
  <dt>
    Related topics</dt>
  <dd>
    A list of links to landing pages for other, related, technologies of relevance. The heading should use the class "Related_Topics".</dd>
</dl>
<h2 id="images">Using, inserting images</h2>
<p name="Other_references">It's possible to have images in the articles you create or modify. It sometimes nice to have to have texts looks less uninviting, especially very technical ones.</p>
<p name="Other_references">The preferred way is the following:</p>
<ol>
  <li name="Other_references">Attach the desired image file to the article (at the bottom of every article in edit mode)</li>
  <li name="Other_references">Create an image in the WYSIWYG editor</li>
  <li name="Other_references">In the WYSIWYG editor in the drop-down list listing attachments, select the newly created attachment which is your image</li>
  <li name="Other_references">Press OK, it's done</li>
</ol>
<h2 id="Other_references" name="Other_references">Other references</h2>
<h3 id="Preferred_style_guides" name="Preferred_style_guides">Preferred style guides</h3>
<p>If you have questions about usage and style not covered here, I recommend referring to the <a class="external" href="http://www.economist.com/research/StyleGuide/">Economist style guide</a> or, failing that, the <a class="external" href="http://www.amazon.com/gp/product/0226104036/">Chicago Manual of Style</a>. The <a class="external" href="http://styleguide.yahoo.com/" title="http://styleguide.yahoo.com/">Yahoo Style Guide</a> covers many topics that are specific to writing on and about the Web, and it keeps current with online usage. You should also read the <a href="/Project:En/MDC_style_guide" title="MDC_style_guide">MDN formatting guide</a>, which offers insight into formatting and layout standards we use.</p>
<h3 id="Preferred_dictionary" name="Preferred_dictionary">Preferred dictionary</h3>
<p>For questions of spelling, please refer to <a class="external" href="http://www.answers.com/library/Dictionary">Answers.com</a>. The spell-checker for this site uses American English. Please do not use variant spellings (e.g., use <em>honor</em> rather than <em>honour</em>).</p>
<p>We will be expanding the guide over time, so if you have specific questions that aren't covered in this document, please send them to the <a href="/Project:en/Community" title="Project:en/Community">MDC mailing list</a> or <a href="/User:Sheppy" title="User:Sheppy">project lead</a> so we know what should be added.</p>
<h3 id="MDC-specific" name="MDC-specific">MDC-specific</h3>
<ul>
  <li><a href="/Project:en/Custom_CSS_Classes" title="Project:en/Custom_CSS_Classes">Custom CSS classes</a> defined for all MDC pages.</li>
  <li><a href="/Project:en/Custom_Templates" title="Project:en/Custom_Templates">Custom templates</a> created for use on MDC, with explanations.</li>
  <li><a href="/Project:en/How_to_Help" title="Project:en/How_to_Help">MDC policies and guidelines</a>:
    <ul>
      <li>If you're not sure how to name your page, see <a href="/Project:en/Page_Naming_Guide" title="Project:en/Page_Naming_Guide">Page naming guide</a>.</li>
      <li><a href="/Project:en/Disambiguation" title="Project:en/Disambiguation">MDC:Disambiguation</a></li>
    </ul>
  </li>
</ul>
<h3 id="Other_resources" name="Other_resources">Language, grammar, spelling</h3>
<p>If you're interested in improving your writing and editing skills, you may find the following resources to be helpful.</p>
<ul>
  <li><a class="external" href="http://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">On Writing Well</a>, by William Zinsser (Amazon link)</li>
  <li><a class="external" href="http://www.bartleby.com/141/">Elements of Style</a>, by Strunk and White</li>
  <li><a class="external" href="http://www.bartleby.com/64/">American Heritage Book of English Usage</a></li>
  <li><a class="external" href="http://www.wsu.edu/~brians/errors/">Common Errors in English</a></li>
  <li><a class="external" href="http://www-personal.umich.edu/~jlawler/aue.html">English Grammar FAQ</a> (alt.usage.english)</li>
  <li><a class="external" href="http://www.angryflower.com/bobsqu.gif">Bob's quick guide to the apostrophe, you idiots</a> (funny)</li>
  <li><a class="external" href="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2" title="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster's Concise Dictionary of English Usage</a> (Amazon link):&nbsp;Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.</li>
</ul>
Revert to this revision