GNOME.org

Grammar and Usage Guidelines

This chapter contains an alphabetical list of grammar and usage guidelines for use in GNOME documentation. Many of these guidelines are only applicable to English-language usage, see the http://www.bartleby.com/61/ and the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.

Abbreviations
Rules:

A shortened form of a word or phrase that takes the place of the full word or phrase, for example Dr., a.m., p.m., and so on.

Apply the following rules when you use abbreviations:

  • Avoid creating new abbreviations. Unfamiliar abbreviations can confuse rather than clarify a concept.
  • Do not explain or expand familiar abbreviations.
  • Do not include familiar abbreviations in the glossary of your manual.
Adjectives
Rules: Use adjectives with caution. If an adjective is necessary to differentiate between items, then use adjectives. In all cases, test whether the phrase can stand alone without the adjective.
Acronyms
Rules:

A term that represents a multi-word term. Typically, acronyms are formed in the following ways:

  • From the first letters of each word in a compound term, for example Table of Contents (TOC).
  • From recognizable parts of a compound term, such as GNU Object Model Environment (GNOME).

Apply the following rules when you use acronyms:

  • On the first occurrence of an acronym, spell out the full term, with the acronym in parentheses.
  • Do not spell out the full compound for well-known acronyms, unless you think the information is useful for readers.
  • Avoid creating new acronyms. Unfamiliar acronyms can confuse rather than clarify a concept.
  • Write the acronym in uppercase letters, unless there is a compelling case for lowercase.
  • Include the acronym and the full term in the glossary of your manual.
Adverbs
Rules: Use adverbs with caution. If an adverb is necessary to qualify the function of a component, then use an adverb. In all cases, test whether the phrase can stand alone without the adverb. Classic superfluous adverbs are: simply, easily, quickly.
Anthropomorphism
Rules:
  • Do not apply emotions, desires, or opinions to software applications.
  • Do not apply a sense of location or dimension to a software application. You can not be in a text editor.
Apostrophe
Rules:
  • Do not use apostrophes to denote possession.
  • Do not use apostrophes to denote contractions.
  • Do not use apostrophes to denote plurals.
Articles
Rules:

Do not use the definite article the to begin any of the following items:

  • Manual titles
  • Chapter titles
  • Headings
  • Figure captions
  • Table captions
  • Callouts
Brackets
Rules:
  • Do not use brackets [such as these] as a substitute for parentheses (such as these).
  • Use brackets for optional command line entries.
  • Do not use angle brackets to indicate variables in text, instead use the replaceable tag.
Capitalization
Rules:

Capitalize in the following situations:

  • All letters in acronyms, unless the acronym is a well-known exception
  • Initial letter of the first word in a list
  • Initial letter of the first word in a callout
  • Initial letter of a key name, such as the Shift key
  • Initial letter of a sentence. Avoid starting a sentence with a command name or application name that has a lowercase initial letter
  • Initial letter of a complete sentence after a colon

Do not capitalize in the following situations:

  • A compound term that is followed by an abbreviation or an acronym
  • When you want to emphasize something
  • Variable names
  • The initial letter of the first word following a colon, if the word is part of an incomplete sentence
Captions
Rules:
  • Use the same rules as for headings, for all captions accompanying figures and tables.
  • Do not put a period at the end of a caption.
Colon
Rules:

Use a colon in the following situations:

  • To introduce a list
  • Before an explanation
  • After an introduction

Do not use a colon in the following situations:

  • To introduce a figure or a table
  • To introduce headings
  • At the end of an introduction to a procedure

Column headings
Rules:
  • Use the same rules as for headings.
Comma
Rules:

Use commas in the following situations:

  • To separate items in a series
  • To separate the parts of a sentence
  • To separate nonrestrictive phrases
  • Instead of dashes to set off appositives
  • With for example and similar expressions

Do not use commas in the following situations:

  • In a series of adjectives used as one modifier
  • Between two short independent clauses
Commands
Rules: Do not use commands as verbs.
Contractions
Rules: Do not use contractions such as can't, don't, or isn't.
Dash
Rules: Do not use the em dash or the en dash. Use a paragraph break or a colon instead, where you want to create an introductory piece of text. If you have several items that you want to introduce, then you can use a variable list.
Ellipsis
Rules:

Use an ellipsis in the following situations:

  • To show that you have omitted something from a sentence
  • To indicate a pause when you quote displayed text
Fractions
Rules:
  • Use numerals for fractions in tables and in units of measurement, but spell out fractions in prose.
  • Use a space between a numeral and a related fraction, if there is a possible ambiguity. For example: 1 1/2 instead of 11/2.
  • If a fraction is used in a compound modifier, insert a hyphen between the fraction and the unit of measurement.
Gender
Rules: See Section 1.4.4 ― Do Not Offend Your Audience.
Grammar
Rules: Use standard American English grammar rules, see the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
Headings
Rules:

Use the following capitalization rules in headings:

  • Initial uppercase letter for the first word and the last word, regardless of part of speech
  • Initial uppercase letter for all nouns, adjectives, and verbs
  • Initial uppercase letter for conjunctions of four letters or longer
  • Initial uppercase letter for prepositions of four letters or longer
  • Initial uppercase letter for prepositions that are part of a phrasal verb
  • All lowercase letters for conjunctions, articles, and prepositions of less than four letters

See Section 2.1 ― Section Headings for more information about headings.

Hyphen
Rules:

Use hyphens in the following situations:

  • With a numeral in a compound modifier
  • To prevent ambiguity
  • With some standard prefixes and suffixes. Use the http://www.bartleby.com/61/ for guidance
  • In spelled-out fractions
  • In variable names of two or more words, such as directory-name. Note: filename is an exception.

Do not use hyphens in the following situations:

  • For industry-accepted terms
  • To construct verbs
  • With an adverb ending in ly
  • With numerals as single modifiers
  • With a word that is listed as unhyphenated in the http://www.bartleby.com/61/, and that uses a common prefix
  • With trademarked terms
Latin terms
Rules: Do not use Latin terms. Use an equivalent English term instead.
Like
Rules: Do not use the term like to denote equivalence or similarity.
Lists
Rules: Introduce a list with a complete sentence that ends with a colon.
Numbers
Rules:

Spell out numbers in the following situations:

  • Numbers from zero through nine unless the number is part of a measurement.
  • Approximations.
  • Extreme values such as million, but precede the value with a numeral
  • Any number that begins a sentence
  • A number that is immediately followed by a numeral, for example: two 10 MB files
Numerals
Rules:

Use numerals in the following situations:

  • The number 10 or greater
  • Negative numbers
  • Most fractions
  • Percentages
  • Decimals
  • Measurements
  • Units of time smaller than one second
  • References to bits and bytes
Parentheses
Rules:

Use parentheses in the following situations:

  • To contain the abbreviation of a term on the first occurrence of the full term
  • In man page references, specifically the section number
Period
Rules:

Use a period in the following situations:

  • To end a sentence
  • In file and directory names
  • In abbreviations that can be mistaken for words, such as a.m. and U.S.
Punctuation
Rules: Use standard American English punctuation rules. In addition to the specific points of punctuation in this section, see also the http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html.
Punctuation in numbers
Rules:
  • Do not use a comma in numerals of four digits.
  • Use a comma in numerals of more than four digits.
Quotation marks
Rules:
  • Use quotation marks to indicate material that is taken verbatim from another source.
  • Do not use quotation marks to excuse terms from legitimacy. If the term is not legitimate, then use another term. If you must use that term, declare the term in the glossary and make the term legitimate.
Semicolon
Rules: Do not use semicolons.
Spelling
Rules: Use standard American English spelling rules, see the http://www.bartleby.com/61/ for guidelines.
Titles
Rules: For manual titles use the same rules as for headings.
Units
Rules:
  • Use standard abbreviations for units of measurements, do not invent your own abbreviations.
  • See Appendix B ― Units for a list of units relevant to the GNOME Desktop. For further guidelines, see the IEEE Standard Dictionary of Electrical and Electronics Terms.
  • Use periods for abbreviated units that might be mistaken for a word.
  • Most standard abbreviations of units account for both singular and plural usage.
  • Insert a space between the numeral and the unit of measurement.
Endnotes and Footnotes Writing Documentation for an International Audience

About