Grammar Girl's Guide to the English Language

Grammar Girl's Rules of Thumb

 

Abbreviations and Acronyms

An abbreviation is a shortened form of a word. An acronym consists of the initial letters of a name or series of words.

​

Abbreviations

Generally, avoid abbreviations in technical writing.

​

DO

Define an abbreviation in its first use.

​

Do NOT

• Abbreviate the names of states unless used with zip codes in addresses.

​

• Use Latin abbreviations in text as shown here: 

  • For example = e.g.

  • Such as = i.e.

  • And so on = etc.

​

Acronyms

Using the articles a or an before an acronym depends on its pronunciation. If the initial sound is a vowel sound, use an; if you hear a consonant sound, use a.

​

Example: a CGI library, an HTML document

​

If the word begins with the vowel u, use the article a because this vowel produces a consonant sound.

​

Example: a utility bill

​

DO

• Write acronyms in complete capital letters.
  Examples: CGI, HTML

​

• Define an acronym in its first full use, followed by the acronym in parentheses. After it is defined, use the acronym throughout the text.
  Example: define Hypertext Mark-up Language (HTML)

​

Do NOT

• Use apostrophes to indicate plurals with acronyms.
  Example: PCs not PC's

 

• Use periods in acronyms.

​

 

Active versus Passive Voice

Use the active voice whenever possible. There are many advantages to using active voice:

​

• Sentences/phrases are simpler and shorter.

• Responsibility is more clearly defined.

• Active voice is more forceful.

• The reader is more easily engaged.

 

Follow these suggestions to write in active voice:
 

• Begin the sentence with the actor.
  Example: The clerk completes the form.
   

• Begin the sentence with the verb when the subject is implied.
  Example: 
  Correct: Complete the form.
  Incorrect: You should complete the form.

​

 

Apostrophes

Use an apostrophe to indicate possession.

 

Although an apostrophe is also used to indicate a contraction (for example: can't, don't), avoid using contractions in technical writing.

​

Note: It's is only used to indicate a contraction. Its is the proper way to indicate possession.

 

Avoid apostrophes to indicate plurals, especially with acronyms. See Acronyms and Plurals in this chapter.

​

 

Brackets

Use brackets to avoid double sets of parentheses.

 

Example: [Process (information) flow]

​

 

Capitalization

Use capitalization consistently and in accordance with your intended meaning. Users look to capitalization for clues as to whether they are reading about something specific to the system or something in general.

​

Full Capitalization

​

DO

• Write acronyms in complete, capital letters. See Acronyms.

 

Do NOT

• Use full capitals to emphasize sentences or paragraphs. Text written in all caps is difficult to read. Also, with the advent of on-line communication, text written in full caps has come to mean yelling.

 

Initial Capitalization

Capitalize the first letter of the following: 

​

• The first word in a sentence

• The first word of each phrase in any list

• The words Building, Room, Figure, Table, and similar words when used with a number

• Proper nouns, that is, names of people, places, and things

• Each word in official job department and organizational unit names

• Each word in official job titles and functional titles

• Trade names and manufacturers' names

• Names of nationalities and languages

• Points of the compass when referring to a region

• Principal words, including the first and last, when referencing official document titles and headings or titles within documents

 

Short articles, conjunctions, and prepositions are not principal words in titles and should therefore be lowercase, as shown in the following examples:

 

• after

• as

• for

• in

• too

• under

• among

• at

• from

• of

• over

• with

• an

• but

• if

• on

• than

• and

• by

• onto

• the

 

Capitalize the first letter of longer prepositions, such as Between and During.

​

 

Lowercase Words

Use lowercase lettering for the following:

​

• Generic system or hardware names

• Chemical element names

• Unofficial job titles in text

• Incomplete or unofficial names of documents or forms

 

Examples: data processing program; hydrogen, oxygen, nitrogen; The president signed a bill.

 

Note: In the following example, the capitalization changes with the use of a proper noun:
President Clinton signed a bill.

​

 

Colons

Colons cause some of the most common grammatical errors in technical writing. Since the use of colons cannot be avoided, it is important to learn the proper guidelines. For an in-depth look at colons, please refer to the latest edition of The Chicago Manual of Style.

​

DO

• Use a colon to indicate a series in a sentence.
  Example: The web site had four separate HTML documents: Links, Biography, Resume, and Home.

 

• Use a colon at the end of a complete introductory sentence preceding a list. Be careful to avoid placing a colon after a verb.
  Examples:

Incorrect: 
The web site includes:

• Links

• Biography

• Resume

• Home

Correct: 
The web site includes the following:

• Links

• Biography

• Resume

• Home

 

Do NOT

• Use a colon to separate a preposition and its object or a verb and its object, as seen in the incorrect example above.

​

 

Commas

 

DO

• Use a comma before the conjunction (and, or) in a series of three or more items.
  Example: This includes Apple, NeXT, and Pixar.

 

• Use a comma to set off an introductory clause or phrase.
  Example: As necessary, the manager works with various departments to execute decisions.

 

• Use a comma when referring to a specific date, but not when referring to a month and year.
  Examples: January 14, 1997 |  January 1997

 

Do NOT

• Do not set off restrictive clauses with commas. In other words, do not set off any clause that could not be removed from the sentence without distorting its meaning. As a general rule, use a comma with the word which and not with the word that.
  Examples: 
  Restrictive clause: There are a lot of web pages that are not safe for children.
  Unrestrictive clause: Safe Surf rates web pages, which reassures parents of the page content.

 

• Do not use a comma to separate two complete thoughts or ideas. This creates a comma splice.
  Examples:
  Incorrect: Certain actions require explanation, other actions may cause an irrevocable action to be taken.
  Correct: Certain actions require explanation; other actions may cause an irrevocable action to be taken.

 

• Do not use run-on sentences, which are created when a comma is omitted.
  Examples:
  Incorrect: If government takes over the Internet a lot of changes will be expected.
  Correct: If government takes over the Internet, a lot of changes will be expected.

​

​

Dashes

Avoid the dash in technical writing. However, if you must use the dash, keep the following rules in mind.

 

There are three major types of dashes: the hyphen - , the em-dash --- , and the en-dash -- . The most common types used are hyphens and the em-dash.

 

The em-dash (---) is used to indicate a break greater than that signaled by a comma. This element is added to indicate a sudden break in thought, to give emphasis or explanation by expanding a phrase occurring in the main clause, to set off a final summarizing clause, or to precede expressions such as that is or namely.

 

Use the en-dash (--) in a series of numbers, such as a phone number.

 

For information on hyphens, see Hyphens.

​

 

Emphasis

Use emphasis sparingly in technical writing. Although it is best avoided, at times emphasis can make a document more friendly. An ideal place to use emphasis is within an Instructor Guide to help articulate key points. Use of emphasis is left to the author's discretion, with Editorial approval during the review process.

​

 

Gender Neutral Language

Using he, him, or his is prohibited in technical documentation. Achieve gender neutral language in several ways:

​

• Write procedural text in commands.

• Refer to personnel functions in the plural.

• Repeat the noun rather than using he or him.

 

If you cannot avoid a singular third person construction, use one of the following as appropriate: he or she, him or her, or his or her.

​

​

Hyphens

 

Word Division

Avoid hyphenation at the end of a line.

​

Compound Words and Unit Modifiers

Compound words can function as nouns, verbs, and adjectives. As adjectives, they are also called unit modifiers.

 

Examples:
Nouns: brother-in-law, ex-mayor
Verbs: spell-check, double-space
Adjectives: long-range, half-hearted attempt

 

Hyphenate two or more words that act together to modify another word. This rule applies only when the connected or compound modifier occurs before the word it modifies.

​

Examples:
Correct: The project called for end-user documentation. 
They received up-to-date information. 
This is a well-documented program.
Incorrect: The documentation was written for the end-user. 
The program is well-documented. 
The information is up-to-date.

 

Do not hyphenate compound words that act as adjectives if the first word ends in -ly.

​

Example: highly trained users, historically based data

 

Prefixes and Suffixes

Use a hyphen when

​

• The prefix ends in a or I and the base word starts with the same letter.
  Example: anti-intellectual
   

• The hyphen is needed to prevent mistaking the intended word for another.
  Example: re-mark vs. remark
   

• The word is likely to be mispronounced without the hyphen.
  Example: co-op vs. coop
   

• The base word is capitalized.
  Example: post-Newtonian
   

• The base is a number.
  Example: pre-1997

 

Do not use hyphens with the following prefixes unless misleading or awkward letter combinations result:

 

• pre

• sub

• mini

• micro

• post

• super

• multi

 

Hyphenation of Numbers

 

DO

• Hyphenate the following:

  • Between numbers and words that form a unit modifier
    Examples: 10-mm diameter rod (or a rod 10 mm in diameter); a five-member panel (or a panel of five)

  • Spelled-out compound numbers from twenty-one to ninety-nine

  • Spelled-out fractions except when a hyphen is already in use
    Examples: one-half, two one-thousandths

 

Do NOT

• Do not hyphenate a modifier consisting of a number followed by a possessive noun
  Examples: two months' layoff, one day's pay
   

​

Lists

Use both numbered and unnumbered lists. Use numbered lists when you need to emphasize sequence. Use unnumbered lists in all other cases.

​

Lists may have multiple levels. It is important to remember that in any list, you cannot have a single item. In numbered lists, you cannot have an "a without a b" or "a 1 without a 2." In unnumbered (bulleted) lists, you must have at least two bullets.

​

The following standards apply to both types of lists:

​

• Precede all lists with an introductory sentence or phrase ending in a colon.

• Capitalize the first letter of the first word of all list entries.

• Do not punctuate (no periods) list entries unless they are complete sentences. If the list entry is the continuation of a stem sentence, do not add a period.

• Ensure that items in a list are parallel in structure. Begin each item with the same part of speech, such as nouns, verbs, or adjectives.

​

Numbered Lists

Numbered lists are aligned at the left margin and carry Arabic numerals with sublevels (if needed) and indentation as shown in the following example:

​

Example:

Upload your web page in the following manner:

1. Open your Browser.

a. Make sure you are connected to your carrier.

b. Make sure you have all your files organized.

2. Go to the Geocities home page.

3. Find the EZ Upload in the File Manager.

 

Unnumbered Lists

Unnumbered lists include bullets and are aligned at the left margin. Sublevels (if needed) and indentation are as shown:

 

Example:
Geocities provides the following services:

• CGI Library

  • Guestbook

  • Forms

• File Manager

• Profile Editor

​

 

Notes and Cautions

Notes and cautions are informational statements used to supply the procedure steps with additional information to improve performance accuracy. Each statement applies to a specific step or sequence and contains only one idea.

 

Use a note to provide helpful or advisory information that does not relate to potential risk of hazard or error. Do not include action steps in a note.

 

Use a caution to provide information concerning any potential risk of hazard or error associated with personal safety, equipment safety, the integrity of software or data, or task performance. Do not include any action steps in cautions.

​

 

Numbers and Units of Measure

 

Units of Time and Measure

• Do not use periods in abbreviations for units of measure.
  Example: kg
   

• Express units of measure, distance, and time in numerals.
  Example: 100 feet  | 2 miles |  1.5 kg  | 17 minutes
   

• If dimensions are required to be given in both U.S. and metric measurements, display the U.S. measurement first followed by the metric equivalent in parentheses.
  Examples: 
  Width: 21.2 inches (538 millimeters)
  Temperature: 50-90F (10-32C)
   

Note: Except for use of the degree symbol, there is a space between the number and the unit of measure. However, if the value is taken verbatim from an equipment label or computer screen, use the exact spacing shown.

 

Use of Numerals

• Use numerals when referring to numbers larger than nine.

• Use numerals in mathematical expressions, percentages, expressions of date and time, and decimals.

 

Sentences Containing One Number

If a sentence contains only one number, use a numeral if it is 10 or more. If the number falls between one and nine, spell it out.

 

Sentences Containing Two or More Numbers

 

• If a sentence contains two or more numbers that are not units of measure, and at least one number is greater than 10, use numerals for all. Otherwise, spell out each number.
  Examples: 
  Each of 15 major commodities, 9 metal and 6 nonmetal, was available. 
  Each of nine major commodities, five metal and four nonmetal, was available.
   

• Numbers that express units of time or measure do not affect other numbers within a sentence.
  Examples: 
  Each of the 15 legs of the race is approximately 10 miles. 
  Each of the five legs of the race is approximately 10 miles.

​

Ordinal Numbers

Spell out numbers (such as first, second, and third) if they are single words. Write them as numerals if they are not.

Examples: 
Schedule slips occurred during the second, fifth, and eighth week of training. 
The team finished the 24th revision.

 

Spelling Out Numbers

 

• Spell out the numbers one through nine.
   

• Always spell out any number when it is the first word of a sentence.
   

• Spell out numbers less than 100 that precede a compound modifier containing a numeral.
  Example: twelve 2-pound packages
   

• Spell out rounded and approximate numbers
  Examples: more than five hundred people; less than one million

​

​

Parentheses

Use parentheses to set off explanatory or supplementary information.

​

Example: Hypertext mark-up language (HTML) is the language of the Internet.

 

Avoid overuse of parenthetical material because it breaks the flow of the sentence.

​

 

Periods

 

DO

• Use a period to indicate the end of all complete sentences.

• Use a period at the end of a complete sentence in a bulleted list only if the list is preceded by a complete sentence (see Colons).

 

Do NOT

• Use periods in acronyms or abbreviated units of measure.

• Use periods at the end of phrases in a bulleted list.

​

 

Plurals

• Use apostrophe s to form the plurals of singular letters and numbers.

• Add a lowercase s to form the plural of initialisms or acronyms.

• Add s to form the plural of dates. With decades, be consistent. For example, choose between using   1980s and 1990s versus the 80s and 90s.

​

 

Question Marks

Use the question mark at the end of an interrogative statement.

​

Example: Did you use a question mark?

​

 

Quotation Marks

 

• Use quotation marks to set off quoted material.
   

• Place an ending punctuation mark, such as a period, comma, or question mark, inside a closing quote regardless of the sense of the sentence. A colon, however, is always placed outside of quotation marks.
  
  Examples: 
  The instructor prodded, "Did you click the correct button?" to find out why I was on the wrong screen.
  The President stated, "Read my lips. No new taxes."

​

 

Semi-Colons

Although the semi-colon is generally avoided by technical writers, there are occasions where its use is required in order to communicate the intended flow of thought. For more information on the use of semi-colons in technical writing, refer to the Handbook of Technical Writing (St. Martin's Press, 1987) or Houp & Pearsall's Reporting Technical Information (MacMillan, 1992).

 

The semi-colon has restricted usage, as follows:

​

• Use a semi-colon to link two related but independent clauses in a sentence. Using the semi-colon in this manner communicates that the two clauses have a closer relationship than would be conveyed in two separate sentences.
  Example: The web master is responsible for identifying abnormal situations; if necessary, these situations can be handled as a change to the files.
   

• Use a semi-colon to separate a series of items internally punctuated with commas.
  Example: Their vacation plans included travel to San Diego, California; Santa Fe, New Mexico; and Pheonix, Arizona.

​​

 

Sentences

 

DO

• Limit sentence length to 8-12 words. Limit paragraphs to 3-4 sentences in technical writing only.
   

• Begin sentences with a logical subject instead of it or there.
   

• Begin explanations with the key item or word.
  Examples:
  Correct: Clarity is an important element of good writing.
  Incorrect: An important element of key writing is clarity.

 

• Use imperative sentences beginning with a verb to give directions or commands.

 

Do NOT

• Use vague intensifiers such as quite, somewhat, definitely, and very.

​

 

Smothered Verbs

Do not use smothered verbs. A smothered verb is "smothered" by a -tion or other suffix. You can usually replace a smothered verb with the same verb in active voice.

​

Example: initialization = initialize

​

 

Spelling

In some cases, the chosen spelling of certain words is a style decision. This section provides some basic guidelines.

​

Preferred Spelling

Follow these rules:

​

• If the dictionary lists two spellings, use the first.
   

• If the word is listed as a variant of another word, use the original word, not the variant.
   

• If you are quoting a source document or program, reflect the spelling in the text you are referencing but make sure to credit your source.

​

Merged Verbs

A spelling problem, particularly in technical documentation, is created by "merged verbs." A merged verb is a verb linked to an adverb, such as shut down. The correct spelling is determined by how the expression is used in the sentence.

Verbs are spelled as two words; nouns and adjectives as one word or hyphenated.

 

Examples:

• log on / logon

• log off / logoff

• start up / startup

• shut down / shutdown

 

Examples in sentences:​

• Verb: To log onto the system, type your password

• Noun: After a few seconds, the system displays the logon screen.

• Verb: Start up the computer.

• Noun: ERP startup is scheduled for early July.

​

 

Tense

 

• Use present tense whenever possible to eliminate mood shifts.
  Example:
  Correct: The test proves nothing wrong. 
  Incorrect: The test proved nothing is wrong.
   

• Keep the verb in agreement with its subject.
  Example:
  Correct: The dates for the implementation are in June. 
  Incorrect: The dates for the implementation is in June.

• ​