# 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 American Heritage Dictionary and the Chicago Manual of Style.

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 .

Grammar

  Rules: | Use standard American English grammar rules, see the Chicago Manual of Style.

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 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 American Heritage Dictionary 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 American Heritage Dictionary, 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 Chicago Manual of Style.

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 American Heritage Dictionary 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 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.