Writer's guide

  • Revision slug: Project:Writer's_guide
  • Revision title: Writer's guide
  • Revision id: 70091
  • Created:
  • Creator: Dria
  • Is current revision? No
  • Comment

Revision Content

{{template.Devmo_editor_TOC()}}

Introduction

This writer's guide is our "house style" for the Mozilla Developer Center project. It is intended to be a friendly guide, rather than a strict set of rules. You are free to ignore this guide, but do not be upset or surprised if an industrious volunteer comes along at some later time and edits your work to conform more closely to this guide.

Preferred style guides

If you have questions about usage and style that aren't covered there, I recommend referring to the Economist style guide or, failing that, the Chicago Manual of Style.

Preferred dictionary

For questions of spelling, please refer to Answers.com. Do not use variant spellings (e.g. use honor rather than its variant honour).

We will be expanding the guide over time, so if you do 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.

Page name and heading capitalization

  • Page names and section headings should use sentence style capitalization (only capitalize the first word and any proper nouns) rather than headline style capitalization:
    • Correct: "A new method for creating JavaScript rollovers"
    • Incorrect: "A New Method for Creating JavaScript Rollovers"
For the time being these capitalization rules for page names apply only to new pages. There are a large number of pages in our wiki that do not conform to these rules, but please do not correct those at this time. We will sort out the logistics and fix older page names at some point in the future. Thanks. -- dria 09:20, 14 March 2006 (PST)

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:
    • Incorrect:

In running text

  • In regular text (i.e. text outside of notes or parentheses), use the English equivalent of the abbreviation.
    • Correct:
    • Incorrect:

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
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 for 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, introduce its expansion in parentheses.
    • Correct: "XUL (XML User Interface Language) is Mozilla's XML-based language..."
    • Incorrect: "XUL is Mozilla's XML-based language..."
Exceptions
  • Expand only those acronyms likely to be unfamiliar to users. When in doubt, expand it.

Plurals of acronyms and abbreviations

  • For plurals of acronyms or abbreviations, add s.
    • Correct: CD-ROMs
    • Incorrect: CD-ROM's

Contractions

  • You are welcome to 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, octopusses
    • Incorrect: syllabi, octopi

Hyphenation

  • Hyphenate compounds in which the last letter of a prefix ending in a vowel is the same as the first letter of the root.
    • Correct: email, re-elect, co-op
    • Incorrect: e-mail, reelect, coop

Numbers and numerals

The date stuff here may change.

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

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 comma is the comma that appears before "and" 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

Revision Source

<p>
{{template.Devmo_editor_TOC()}}
</p>
<h3 name="Introduction"> Introduction </h3>
<p>This writer's guide is our "house style" for the Mozilla Developer Center project.  It is intended to be a friendly guide, rather than a strict set of rules.  You are free to ignore this guide, but do not be upset or surprised if an industrious volunteer comes along at some later time and edits your work to conform more closely to this guide.
</p>
<h4 name="Preferred_style_guides"> Preferred style guides </h4>
<p>If you have questions about usage and style that aren't covered there, 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>.
</p>
<h4 name="Preferred_dictionary"> Preferred dictionary </h4>
<p>For questions of spelling, please refer to <a class="external" href="http://www.answers.com/library/Dictionary">Answers.com</a>.  Do not use variant spellings (e.g. use <i>honor</i> rather than its variant <i>honour</i>).
</p><p>We will be expanding the guide over time, so if you do have specific questions that aren't covered in this document, please send them to the <a href="Project:en/Community">MDC mailing list</a> or <a href="User:Dria">project lead</a> so we know what should be added.
</p>
<h3 name="Page_name_and_heading_capitalization"> Page name and heading capitalization </h3>
<ul><li> Page names and section headings should use sentence style capitalization (only capitalize the first word and any proper nouns) rather than headline style capitalization:
<ul><li> <font color="green"><b>Correct</b></font>: "A new method for creating JavaScript rollovers"
</li><li> <font color="red"><b>Incorrect</b></font>: "A New Method for Creating JavaScript Rollovers"
</li></ul>
</li></ul>
<div class="note">For the time being these capitalization rules for page names apply only to new pages.  There are a large number of pages in our wiki that do not conform to these rules, but please do not correct those at this time.  We will sort out the logistics and fix older page names at some point in the future.  Thanks.  -- <a href="User:Dria">dria</a> 09:20, 14 March 2006 (PST)</div>
<h3 name="Latin_abbreviations"> Latin abbreviations </h3>
<h4 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> <font color="green"><b>Correct</b></font>: 
</li><li> <font color="red"><b>Incorrect</b></font>: 
</li></ul>
</li></ul>
<h4 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> <font color="green"><b>Correct</b></font>:
</li><li> <font color="red"><b>Incorrect</b></font>: 
</li></ul>
</li></ul>
<h4 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><i>confer</i></td>
<td>compare</td>
</tr>
<tr>
<td>e.g.</td>
<td><i>exempli gratia</i></td>
<td>for example</td>
</tr>
<tr>
<td>et al.</td>
<td><i>et alii</i></td>
<td>and others</td>
</tr>
<tr>
<td>etc.</td>
<td><i>et cetera</i></td>
<td>and so forth, and so on</td>
</tr>
<tr>
<td>i.e.</td>
<td><i>id est</i></td>
<td>that is</td>
</tr>
<tr>
<td>N.B.</td>
<td><i>nota bene</i></td>
<td>note well</td>
</tr>
<tr>
<td>P.S.</td>
<td><i>post scriptum</i></td>
<td>postscript</td>
</tr>
</tbody></table>
<p>N.B. Be careful not to confuse "e.g." with "i.e."
</p>
<h3 name="Acronyms_and_abbreviations"> Acronyms and abbreviations </h3>
<h4 name="Capitalization_and_periods"> Capitalization and periods </h4>
<ul><li> Use full capitals for and delete periods in all acronyms and abbreviations, including organizations such as "US" and "UN".
<ul><li> <font color="green"><b>Correct</b></font>: XUL
</li><li> <font color="red"><b>Incorrect</b></font>: X.U.L.; Xul
</li></ul>
</li></ul>
<h4 name="Expansion"> Expansion </h4>
<ul><li> On the first mention of a term on a page, introduce its expansion in parentheses.
<ul><li> <font color="green"><b>Correct</b></font>: "XUL (XML User Interface Language) is Mozilla's XML-based language..."
</li><li> <font color="red"><b>Incorrect</b></font>: "XUL is Mozilla's XML-based language..."
</li></ul>
</li></ul>
<h5 name="Exceptions"> Exceptions </h5>
<ul><li> Expand only those acronyms likely to be unfamiliar to users.  When in doubt, expand it.
</li></ul>
<h4 name="Plurals_of_acronyms_and_abbreviations"> Plurals of acronyms and abbreviations </h4>
<ul><li> For plurals of acronyms or abbreviations, add <i>s</i>.
<ul><li> <font color="green"><b>Correct</b></font>: CD-ROMs
</li><li> <font color="red"><b>Incorrect</b></font>: CD-ROM's
</li></ul>
</li></ul>
<h3 name="Contractions"> Contractions </h3>
<ul><li> You are welcome to use contractions (e.g. "don't", "can't", "shouldn't") if you prefer.
</li></ul>
<h3 name="Pluralization"> Pluralization </h3>
<ul><li> Use English-style plurals, not the Latin- or Greek-influenced forms.
<ul><li> <font color="green"><b>Correct</b></font>: syllabuses, octopusses
</li><li> <font color="red"><b>Incorrect</b></font>: syllabi, octopi
</li></ul>
</li></ul>
<h3 name="Hyphenation"> Hyphenation </h3>
<ul><li> Hyphenate compounds in which the last letter of a prefix ending in a vowel is the same as the first letter of the root.
<ul><li> <font color="green"><b>Correct</b></font>: email, re-elect, co-op
</li><li> <font color="red"><b>Incorrect</b></font>: e-mail, reelect, coop
</li></ul>
</li></ul>
<h3 name="Numbers_and_numerals"> Numbers and numerals </h3>
<div class="note">The date stuff here may change.</div>
<h4 name="Dates"> Dates </h4>
<ul><li> For dates (not including dates in code samples) use the format: January 1, 1990.
<ul><li> <font color="green"><b>Correct</b></font>: February 24, 2006
</li><li> <font color="red"><b>Incorrect</b></font>: February 24th, 2006; 24 February, 2006; 24/02/2006
</li></ul>
</li></ul>
<h4 name="Decades"> Decades </h4>
<ul><li> For decades, use the format: 1990s.
<ul><li> <font color="green"><b>Correct</b></font>: 1990s
</li><li> <font color="red"><b>Incorrect</b></font>: 1990's
</li></ul>
</li></ul>
<h4 name="Plurals_of_numerals"> Plurals of numerals </h4>
<ul><li> For plurals of numerals add <i>s</i>.
<ul><li> <font color="green"><b>Correct</b></font>: 486s
</li><li> <font color="red"><b>Incorrect</b></font>: 486's
</li></ul>
</li></ul>
<h4 name="Commas"> Commas </h4>
<ul><li> In running text, use commas only in five-digit and larger numbers.
<ul><li> <font color="green"><b>Correct</b></font>: 4000; 54,000
</li><li> <font color="red"><b>Incorrect</b></font>: 4,000; 54000
</li></ul>
</li></ul>
<h3 name="Punctuation"> Punctuation </h3>
<h4 name="Serial_comma"> Serial comma </h4>
<ul><li> Use the serial comma.  The serial comma is the comma that appears before "and" in a series of three or more items.
<ul><li> <font color="green"><b>Correct</b></font>: I will travel on trains, planes, and automobiles.
</li><li> <font color="red"><b>Incorrect</b></font>: I will travel on trains, planes and automobiles.
</li></ul>
</li></ul>
<h3 name="Spelling"> Spelling </h3>
<ul><li> 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.
<ul><li> <font color="green"><b>Correct</b></font>: localize, honor
</li><li> <font color="red"><b>Incorrect</b></font>: localise, honour
</li></ul>
</li></ul>
Revert to this revision