3. Abbreviations, Numbers and Miscellaneous Topics

This chapter discusses Abbreviations, Numbers, Capitalization and additional writing topics. It is divided into five main parts:

	Abbreviations, Acronyms, and Units of Measurement
	Numbers and numerals
	Capitalization
	Bold and italic fonts
	Cliches, Euphemisms, and Sexist Writing

3.1 Abbreviations, Acronyms and Units of Measurement

Computer manuals require extensive use of abbreviations and acronyms, as well as occasionally units of measurement. Many computer acronyms, like the term Internet, are now widely accepted as computer industry words. As with any word, it is important that you use Abbreviations, Acronyms and Units of Measurement accurately and consistently. To do this, rely on industry definitions; never try to create your own. Refer also to books like the IBM Dictionary of Computing and the Microsoft Press Computer Dictionary.

3.1.1 Abbreviations and Acronyms in Text

An abbreviation is a shortened form of a word or phrase that is used in place of the entire word or phrase. CPU (Central Processing Unit), html (Hyper Text Markup Language), and BBS (Bulletin Board System) are examples of abbreviations. An acronym is an easily pronounceable word formed from the initial letters or major parts of a computer term. COBOL (Common Business Oriented Language), BIOS (Basic Input Output System), and LAN (Local Area Network) are examples of acronyms.

Use abbreviations or acronyms in the following cases:

• Write out the full word or phrase the first time you use it and enclose the abbreviation or acronym in parentheses. After that, use the abbreviation or acronym. Example:

• If you cite a term only once or twice in a document, don't shorten it unless the abbreviation or acronym is well known.
• If an abbreviation or acronym appears often in your document, repeat the spelled-out version in each chapter where it is used.
• Do not shorten trademarked terms or spell out trademarked terms that appear to be abbreviations or acronyms.
• When using an acronym, make sure its pronunciation is natural and obvious to a reader. The acronym SCSI, for example is pronounced "scuzzy." A user not knowing that SCSI is pronounceable may expect to see "an SCSI port," not "a SCSI port." In cases like this, provide some kind of pronunciation key where you first use the acronym by itself; for example:

3.1.2 Abbreviations and Acronyms Punctuation

Usually, you do not need to add punctuation to abbreviations and acronyms. However, there are a few exceptions:

• Use periods or other punctuation marks in abbreviations or acronyms when it is standard form. Examples: in. for inch, I/O for input/output, 3-d for three-dimensional.
• Add an "s" and no apostrophe to form the plural of abbreviations or acronyms that do not use internal periods. Examples: PCs, GUIs.
• Add an apostrophe and "s" to form the plural of abbreviations or acronyms that use internal periods. Examples: M.S.'s, Ph.D.'s.

The following table list some common abbreviations and acronyms used in the computer industry. It is not comprehensive and we recommend referring to the resources listed at the beginning of this chapter for any not listed here. New abbreviations and acronyms are being created daily as new technologies emerge, and old ones disappear. Note too that definitions of terms can vary from one computer system to another. Definitions of terms can even vary slightly within the same computer system.

3.1.3 Units of Measurement

Follow these rules when abbreviating units of measurement:

• Do not abbreviate common American units of measurement, such as "inches," "pounds," and "feet" unless you are worried about space (such as within a table column).
• Use standard abbreviations for units of measurement with great care. For example, the difference between Mb and MB is the difference between a megabit and megabyte. You can avoid confusion by always spelling out a term like megabyte or by using the less-abbreviated form, Mbyte.
• Be aware that most abbreviations for units of measurement already account for plurals. For example, the abbreviation for 1 kilowatt and 10 kilowatts is the same: kW.
• leave a space between the numeral and the abbreviation, if an abbreviation for a unit or measurement is more than one letter, but if an abbreviation consists of only one letter, do not leave a space. Examples: 12 mm, 12V.
• Include the metric or U.S. equivalent of a unit of measurement, when appropriate. Examples: 1 in (2.54 cm), 1m (3.2808 ft).

3.2 Numbers and numerals

A number describes a unit within a collection. A number is expressed by numerals (1, 2, 3, 4) or by words. Cardinal numbers use the words "one, two, three," while ordinal numbers use the words "first, second, third." With most manuals, you will most often use numerals when numbers are discussed in text.

3.2.1 Spelling out numbers

Spell out:

• Numbers zero through nine, unless the number is part of a measurement. Examples: three computers (a count), 3 inches (a measurement).
• Approximations. Example: "You can choose from hundreds of Pentium computers."
• Extreme values, such as "million" and "billion," but precede them with a numeral. Example: 3 million instructions per second.
• The first number if a numeral immediately follows the number. Example: Print ten 500,000 byte files.

3.2.2 Using Numerals

Use numerals for

• Numbers 10 or greater.
• Numbers less than 10 if they are of the same type and appear in the same paragraph as numbers of 10 or greater.
• Negative numbers.
• Most fractions.
• All percentages.
• All decimals. Examples: 0.15, 1.25.
• All measurements. Examples: 6 pounds; 3.5-inch disk drive.
• Chapter, section, part, page. figure, and table numbers. Example: Part 4, Chapter 6.

3.2.3 Punctuating Numbers and Numerals

Numbers and numerals generally require the same punctuation as words. Punctuating numbers and numerals can become troublesome when they are compounded.

• Do not hyphenate numbers or numerals when they serve as single modifiers. Example: Your binary file is now 855,000 bytes.
• Hyphenate numbers or numerals in compound modifiers. Examples: Print your 855,00-byte file.
• Do not use a comma in numerals of four digits. Examples: 1028, 6000.
• Use a comma in numerals of more than four digits. Examples: 10,000, 600,000.

3.2.4 Using Fractions

Usage of numerals for fractions depends on the context. Sometimes it may be best to spell out the fraction or use decimals.

• Use numerals for fractions in tables and for units of measurement, but spell out common fractions in running text. Examples: 1/2-inch tape drive, half the users in the test.
• Use a space between a numeral and its related fraction. Example: 8 1/2-inches.
• insert a hyphen, if a fraction is being used as a modifier between the fraction and what it is modifying. Example: 8 1/2-inch width.
• Use decimals when that is the industry standard. Examples: 5.25-inch drive, 3.5-inch drive, 1/2-inch tape drive.
• Spell out a numeric modifier of a fraction. Example: Ten 1/2-inch tape drives (10 tape drives for 1/2-inch tape).

3.2.5 Dates and Times

You may need to include dates and times in your manuals, especially in examples. Follow these rules when expressing dates:

• In examples, use the mmddyy format or May 10, 1997. Always spell out the month name. Avoid the 5/10/97 format. In the US it means May 10, 1997; however in other countries it means October 5, 1997.
• When describing how to enter dates, be clear which number is the month. Example: Enter 5/10/97 for May 10, 1997.

Follow this rule when expressing times:

• Use numbers to express the time of day. Use a colon between hours and minutes (and between minutes and seconds, if needed). Always capitalize AM and PM. Examples:

3.3 Capitalization

Writers tend to use too much capitalization. The main reason to capitalize a word is that it is proper, not because it has greater status than other words. A proper noun identifies a specific member of a class, whereas a common noun denotes either the whole class or any random member of the class.

3.3.1 When to Capitalize

In general, if an article or another limiting word ("a," "the," "this," "some," or "certain,") appear before the noun in question it is a common noun. Example:

Note the difference in these two sentences. In the first sentence, the article "a" makes it clear the writer is talking about a generic text editor. In the second sentence, the absence of an article makes it clear the writer is talking about a specific text editor. In that case, Text Editor should be capitalized.

In general, capitalize:

• The letters of many abbreviations and acronyms.
• The first letter of the first term used in figure callouts and proper nouns in figure callouts.
• The first letter of a table, figure, appendix, chapter, and section when followed by a letter or number. Examples:

• The first letter of the names of function keys on a keyboard. Examples: Control key, Escape key.
• The first letter of the first word of a sentence, unless the sentence begins with a command name or other computer term that is not capitalized.

• The first word of a complete sentence following a colon. Example:

• The first letter of any word in a title or head, with the exception of conjunction and articles, prepositions of fewer than four characters, and the "to" in infinitives, unless they appear at the beginning or end of the title or head.
• Example: See Chapter 3, "Splitting the Infinitive."
• The second element of a hyphenated compound in a title or head, only if it is a noun or proper adjective, or if it has equal force with the first element.
• Example: "Ordering Third Party Peripherals."
• Figure and table captions, using the same rules you establish for titles and heads in your document.

3.3.2 When Not to Capitalize

Do not capitalize:

• The word page or step when it is followed by a number. Example: see page 45.
• The first letter of the words in certain phrases, even though the phrases ordinarily appear in a shortened form in capital letters: Example:

• Any word for the sole reason of emphasizing it (use italics for emphasis).
• Variable names used in code examples.
• Alphanumeric keys in a key combination. Example: Control-q
• Words in figure callouts other than the first word or proper sentence.
• In a title or head, conjunctions, articles, prepositions of fewer than four characters, and the to in infinitives, unless they appear at the beginning or end of the title. Example: Elements of the User Interface.

3.4 Font Conventions

Follow these font conventions:

Bold. For Main chapter topics or important concepts.

Italic. Examples or book titles.

Arial. Same as above.

Courier. For computer messages or commands.

3.5 Miscellaneous Topics

This section addresses miscellaneous writing topics.

3.5.1 Cliches

Cliches are expressions that have been used for so long they no longer sound fresh. In addition to being stale, clichés usually are wordy and often vague. Cliches usually come to mind easily. An example of one is, "Cliches make a writer look dumb as a doornail." They are often used to attempt to make writing sound impressive, but instead slow communication and can even irritate your reader. Avoid them whenever possible.

3.5.2 Euphemisms

Similar in some respects to clichés are euphemisms. Euphemisms are words that are inoffensive substitutes to words that can be distasteful, offensive or too blunt. Used judiciously, euphemisms can help you avoid embarrassing or offending someone; however overuse of them can hide the facts of a situation. Examples: remains for corpse, or incident for accident.

3.5.3 Sexism in Writing

Writers must be careful to avoid their writing does not convey sexism. Up until the not-so-recent past, the pronouns he, him, and his were regarded by some as gender-neutral words. However, today use of these pronouns is considered offensive. Avoid them at all costs. Here are some ways to avoid sexist writing:

• Write plural antecedents and pronouns as often as possible. Instead of saying "his machine," change it to read "their machine."
• Eliminate the possessive as much as possible when you are writing in the third person. Instead of saying "ask his advice," change it to read "ask their advice."
• Use the word you. Instead of saying "If the user wants to change his access," change it to read "If you want to change your access."
• Use gender nonspecific nouns as much as possible. Instead of saying "chairman or mailman," say "chairperson or letter carrier."