Writer's guide

This writer's guide is the house style for the MDN Documentation Center. It is intended to be a friendly set of guidelines rather than a strict set of rules, so you are free to ignore anything here. Do not be upset or surprised, however, if an industrious volunteer later comes along and edits your work to conform to this guide more closely.

Naturally, this guide applies primarily to the English MDC wiki. The other language wikis may have (and are welcome to create) their own writer's guides.

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.

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"

Code snippets

Sample code and code snippets should use two spaces per tab for tabbing; see Code formatting in the MDC style guide for additional style guidelines for sample code.

Larger code samples, including live samples, can be sent by email to be posted onto the MDC site; you'll get back an email with a URL you can link to.

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

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, or, better, link it to the article describing the technology.

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, octopuses
  • 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.
  • <font color="green">Correct</font>: email, re-elect, co-op
  • <font color="red">Incorrect</font>: 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 "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

Other resources

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

• On Writing Well, by William Zinsser (Amazon link)
• Elements of Style, by Strunk and White
• American Heritage Book of English Usage
• Common Errors in English
• English Grammar FAQ (alt.usage.english)
• Bob's quick guide to the apostrophe, you idiots (funny)
• Merriam-Webster's Concise Dictionary of English Usage (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.