This is just the beginning of a writer's guide for the MDC. 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.
For questions of spelling, please refer to the Merriam-Webster online dictionary.
We will be expanding the guide over time, so if you do have specific questions that aren't covered by the writer's guide, 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:
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.
In running text
- In regular text (i.e. text outside of notes or parentheses), use the English equivalent of the abbreviation.
Meanings and English equivalents of Latin abbreviations
|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|
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
- 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..."
- 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
- You are welcome to use contractions (e.g. "don't", "can't", "shouldn't") if you prefer.
- Use English-style plurals, not the Latin- or Greek-influenced forms.
- Correct: syllabuses, octopusses
- Incorrect: syllabi, octopi
- 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
- 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
- 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
- In running text, use commas only in five-digit and larger numbers.
- Correct: 4000; 54,000
- Incorrect: 4,000; 54000
- 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.
- For words with variant spellings, always use the first entry in the Merriam-Webster online dictionary.