Error-free writing requires more than just using good grammar. You must also use correct mechanics of writing in your documents. The mechanics of writing specifies the established conventions for words that you use in your documentation. Grammar reflects the forms of words and their relationships within a sentence. For instance, if you put an apostrophe in a plural word (“Create two file’s”), you have made a mistake in the mechanics of writing, not grammar.
The mechanics of writing guidelines in this chapter work well for computer documentation, but other style guides might suggest different rules that are equally effective. In most cases, which rules you follow doesn’t matter as long as you are consistent within your document or documentation set. See Chapter 2 for options related to the use of text and graphical elements, such as section headings, tables, and cross-references.
This chapter discusses the following topics:
“Capitalization” on page 2
“Contractions” on page 4
“Gerunds and Participles” on page 5
“Numbers and Numerals” on page 6
“Pronouns” on page 10
“Technical Abbreviations, Acronyms, and Units of Measurement” on page 11
“Punctuation” on page 14
The chief reason to capitalize a word is that the word is proper, not because the word has greater status than other words. A proper noun identifies a specific member of a class. A common noun, on the other hand, denotes either the whole class or any random member of the class. For example, King Henry VIII (a particular member of a class) was a king of England (the class itself).
Answering the following question can help you determine whether a noun is proper. If the answer is yes, the noun is probably a common noun.
Does an article or other limiting word appear before the noun? Limiting words include “a,” “the,” “this,” “some,” and “certain.”
Notice the difference between the following sentences:
Use a text editor to change the information in your file.
Use Text Editor to change the information in your file.
In the first sentence, the article “a” makes clear that the writer is not pointing to a particular member of the group of text editors. Therefore, “text editor” is a common noun. But in the second sentence, the absence of an article or limiting word helps to clarify that the writer is pointing to only one member of the group. In that case, capitalize the proper noun “Text Editor.”
Note
Note — See Chapter 13 and Chapter 14 for examples of how to capitalize glossary and index entries, respectively.
Use an industry-accepted dictionary or other resource to verify capitalization of computer terms. Refer to “Reference Works” on page 328 in Appendix D for suggested resources.
Capitalize the following items:
Proper nouns
The letters of many abbreviations and acronyms
The first letter of the first word in numbered or bulleted lists
The first letter of the first word in figure callouts (see “Writing Callouts for Illustrations” on page 214)
The first letter of these terms when they are followed by a letter or number: “table,” “figure,” “example,” “appendix,” “chapter,” “section,” “part,” and “step”
The font style and capitalization in cross-references might differ because these aspects are determined by your template or tool.
Go to Chapter 3.
See Section 9 in the reference manual.
See the following table.
The Roman numeral that designates the sequence of a part divider in a manual
Part III
The first letter of each term that identifies the name of a key on a keyboard
Control-A
Escape key
the M key
Ctrl-Shift-Q
The first letter of the first word in a sentence, unless the sentence begins with a literal command name or other literal computer term that is not capitalized
Write in a way that avoids such occurrences.
Incorrect:
formatenables you to divide the disk into slices.Correct: Use the
formatutility to divide the disk into slices.
The first letter of the first word of a complete sentence following a colon
The software saves time: You can now press a single key to accomplish what used to take hours of complex calculations.
Select from two options: The Save option stores your changes and the Discard option erases your changes.
The first letter of the first word in a title or heading, the first letter of all other words in a title or heading except conjunctions, articles, prepositions of fewer than four letters, and the “to” in infinitives
See “Using the Mouse” on page 11.
How to Delete Text With the Cut Function Key
The first letter of the second element of a hyphenated compound word in a title or heading unless the element is an article, preposition, or coordinating conjunction
Installing a Half-Inch Disk Drive
Configuring the Audio-in Component
Figure captions, example captions, table captions, and table column headings, using the same rules as for titles and section headings
Hardware switch names and buttons
Power-On/Off switch
Standby switch
Power button
Do not capitalize the following items:
The word “page” when followed by a number
Refer to page 45.
The spelled-out words in most acronyms and abbreviations, even though the words ordinarily appear in a shortened form in capital letters
field-replaceable unit (FRU)
direct memory access (DMA)
The “x” in hexadecimal text, as in “0x8E”
The “x” in “x86”
The “x” in dimensions, as in “12x12 inches”
Any word for the sole reason of emphasizing it (use italic for emphasis)
The words “release” or “version” unless these words are part of a product name
Variable names that are used in code examples
Command and function names
Words in figure callouts other than the first word, proper nouns, abbreviations, or acronyms
The first word following a colon if the word begins a text fragment
This button has only one purpose: to shut down the system.
Contractions can potentially cause confusion for localization or nonnative English speakers. When using contractions, follow these guidelines:
Never use a contraction when you want to emphasize the negative.
Incorrect: Don’t press the Escape key.
Correct: Do not press the Escape key.
Avoid obscure contractions, nonstandard usage, and regionalisms such as “mustn’t,” “mightn’t,” ”you’d best,” “shan’t,” “ain’t,” or “don’t” to mean “does not.”
Never create your own contractions.
Avoid adding “’s” for “is” or “has” to form a contraction (for example, “that’s”).
This construction can be confused with possessive constructions.
Use “it’s” and “its” correctly.
“Its” is the possessive of “it.” “It’s” is the contraction of “it is.”
If you must use these constructions, make sure that the antecedent is clear.
Its features include expanding and contracting list items.
It’s the correct contraction to use.
The following contractions are not usually a problem for translators: “can’t,” “isn’t,” and “don’t” (for “do not”).
When you use a gerund or a participle, ensure that the phrase or sentence in which the gerund or the participle is used is unambiguous. A participle is based on a verb, ends with “-ing” or “-ed,” and functions as an adjective. A gerund is also based on a verb and ends with “-ing,” but a gerund is used as a noun.
Confusion can arise when a gerund is followed immediately by a noun because the gerund could be misinterpreted as a modifier. For example, the sentence “Moving companies can be a growth opportunity in an economic decline” is ambiguous because you can interpret “moving” in either of the following ways:
The movement of companies can be a growth opportunity in an economic decline.
The moving services industry can be a growth opportunity in an economic decline.
Follow these guidelines when using gerunds and participles:
Rewrite sentences to avoid gerunds that are immediately followed by nouns.
Note
Tip — In many instances, you can avoid ambiguity by preceding the noun with an article or possessive pronoun.
Incorrect:
Disabling network services prevents IP packets from doing any harm to the system.
Correct:
Disabling the network services prevents IP packets from doing any harm to the system.
The disabling of network services prevents IP packets from doing any harm to the system.
If you disable network services, the IP packets do not harm the system.
Rewrite sentences to avoid participles that have ambiguous meanings.
The following sentence is ambiguous because you do not know whether the participle “using” applies to the term “request” or “Document Editor.”
The Document Editor sends an edit message request using the file name as a parameter for the message.
You can interpret this sentence in either of the following ways:
The Document Editor sends an edit message request that uses the file name as a parameter for the message.
The Document Editor uses the file name as a parameter for the message to send the message.
The following sentence is ambiguous because you do not know whether the participle “used“ applies to the term “variables” or “semaphores.”
Semaphores are almost as powerful as conditional variables used in conjunction with mutexes.
You can interpret this sentence in either of the following ways:
Semaphores are almost as powerful as conditional variables that are being used in conjunction with mutexes.
Semaphores are almost as powerful as conditional variables when the semaphores are used in conjunction with mutexes.
A number is expressed by numerals (1, 2, 3, 4), by Roman numerals (I, II or i, ii), or by words. Cardinal numbers use words such as “one, two, three.” Ordinal numbers use words such as “first, second, third.”
In computer documentation, you most often use numerals when numbers are discussed in text.
Spell out numbers in the following situations:
Numbers from zero through nine, unless the number is part of a measurement or is used in standards that are approved by organizations such as International Organization for Standardization (ISO)
three computers (a count)
3 MIPS (a measurement)
XDR fits into the presentation layer (layer 6) of the ISO reference model.
Common units of time, greater than one second, from zero through nine
five minutes
three days
Approximations
You can choose from hundreds of applications for your computer.
The zeroes in extreme values, such as “million” and “billion,” but precede these words with a numeral
3 million instructions per second
Any number that begins a sentence
Ten files are required.
A number that is immediately followed by a numeral
Print twelve 500,000-byte files.
Print 12 of the 500,000-byte files.
Use numerals in the following cases:
Numbers 10 or greater
Numbers less than 10 if they are of the same type and appear in the same sentence, paragraph, or bulleted list as numbers of 10 or greater
The menu offers 11 options, but you use only 4 options.
Numbers less than 10 if they are used in terms common to standards that are approved by organizations such as International Organization for Standardization (ISO)
XDR fits into the presentation layer (layer 6) of the ISO reference model.
Negative numbers
Most fractions (see “Using Fractions” on page 9)
All percentages
All decimals, including the leading zero
0.15
1.25
All measurements (see “Units of Measurement” on page 13)
6 pounds
3.5-inch disk drive
12×12 feet
Units of time smaller than one second
5 milliseconds
Bit and byte references
4 bytes
8-bit color
Chapter, section, page, step, figure, example, and table numbers
Step 4
Section 6.2
Part numbers. Use uppercase Roman numerals, for example, “Part IV”
Numbers and numerals generally require the same punctuation as words. Punctuating numbers and numerals becomes troublesome, however, when the numbers are compounded. Follow these guidelines:
Do not hyphenate numbers or numerals when they serve as single modifiers.
Your file contains 500,000 bytes.
Hyphenate numbers or numerals in compound modifiers.
Print the 500,000-byte file.
Do not use a comma in numerals of four digits.
1028
6000
Use a comma in numerals of more than four digits.
10,000
600,000
For more information about appropriate use of numbers and numerals, see “Numbers, Symbols, and Punctuation” on page 144.
The usage of numerals for fractions depends on the context. Sometimes, spelling out the fraction or using decimals is the preferred form. Follow these guidelines:
Use numerals for fractions in tables and for units of measurement, but spell out common fractions in running text.
1/2-inch tape drive
half the users in the test
Use a space between a numeral and its related fraction.
8 1/2 inches
If a fraction is used in a compound modifier, insert a hyphen between the fraction and its unit of measurement.
8 1/2-inch width
Use decimals when decimals are the industry standard.
3.5-inch diskette
In a table in which you are using a numeric modifier of a fraction to save space, spell out the modifying numeral to avoid confusion.
In tables: ten 1/2-inch tape drives (there are ten drives for 1/2-inch tape)
In tables: 10 1/2-inch tape drive (the drive is for 10 1/2-inch tape)
Preferred in text: 10 tape drives for 1/2-inch tape
Follow these guidelines for the use of pronouns:
Avoid the indefinite pronoun or indefinite possessive pronoun, especially at the beginning of a sentence, unless the noun to which the pronoun or possessive pronoun refers is clear.
A pronoun that forces a reader to search for an antecedent can frustrate or mislead the reader. Pronouns that typically cause this type of confusion include “it,” “they,” “its,” “theirs,” “this,” “these,” “that,” and “those.”
Incorrect: It also describes how to install the software.
Correct: This chapter also describes how to install the software.
Incorrect: You can use these either individually or together.
Correct: You can use these two options either individually or together.
Incorrect:
The value in this variable is used to determine when to pause during long display output, such as during a software dump. Its value is reset each time the
okprompt is displayed.Correct:
The value in this variable is used to determine when to pause during long display output, such as during a software dump. The variable’s value is reset each time the
okprompt is displayed.
Do not use first person pronouns.
Incorrect:
We recommend that you install the custom components only on large systems.
Correct:
Install the custom components only on large systems.
Incorrect:
We can write a protocol specification that describes the remote version of
printmessage().Correct:
You can write a protocol specification that describes the remote version of
printmessage().
Computer documentation requires extensive use of abbreviations, acronyms, and units of measurement, many of which have become generally accepted “words” in the industry language. As with any word in a sentence, use abbreviations, acronyms, and units of measurement accurately and with consistent meaning in your documents. Do not create your own abbreviations or acronyms. Rely on industry definitions for these terms. Reference books of this type include The New IEEE Standard Dictionary of Electrical and Electronics Terms, IBM Dictionary of Computing, and Microsoft Press Computer Dictionary.
An abbreviation is a shortened form of a word or phrase that is used in place of the entire word or phrase. “CPU” for central processing unit, “Btu” for British thermal unit, and “SGML” for Standard Generalized Markup Language are examples of abbreviations. An acronym is an easily pronounceable word formed from the initial letters or major parts of a compound term. “GUI” for graphical user interface, “pixel” for picture element, and “ROM” for read-only memory are common acronyms.
When using abbreviations or acronyms, follow these guidelines:
Do not use the Latin abbreviations e.g., i.e., vs., op. cit., viz., and etc.
In most cases, write out the full word or phrase and enclose its abbreviation or acronym in parentheses the first time the word or phrase is used.
Then, continue using the abbreviation or acronym alone.
A local area network (LAN) consists of computer systems that can communicate with one another through connecting hardware and software. Your company probably uses a LAN.
Do not spell out acronyms and abbreviations that are trademarked terms.
Avoid using acronyms and abbreviations in the plural form.
Acronyms and abbreviations in the plural form can potentially cause problems for assistive technologies and for localization.
If you cite a term only once or twice in a document, show both the abbreviation or acronym and the spelled-out version at each occurrence.
If an abbreviation or acronym is used often in a document, repeat the spelled-out version at the first appearance in each chapter where the abbreviation or acronym appears.
When writing out the full word or phrase, do not capitalize any letters unless the letters are capitalized as part of a standard or begin a proper noun.
floating-point unit (FPU)
Internet Protocol (IP)
Do not shorten trademarked terms.
When using an acronym, ensure that its pronunciation is natural and obvious to a reader.
The acronym “SCSI,” for example, is pronounced “scuzzy.” A user who does not know that “SCSI” is pronounceable might expect to see “ an SCSI port,” not “ a SCSI port.” In such cases, provide a pronunciation key when you first use the acronym by itself, as in this example:
A small computer system interface (SCSI, pronounced “scuzzy”) cable connects the disk drive to the SCSI port.
While you usually do not have to add punctuation to abbreviations and acronyms, the following list provides a few exceptions:
Use periods in abbreviations that look like words.
U.S. for United States
no. for number
Use punctuation marks other than a period in abbreviations or acronyms when that punctuation is standard form.
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 contain no periods.
PCs
ISVs
GUIs
Add an apostrophe and “s” to form the plural of abbreviations or acronyms that use internal periods.
M.S.’s
Ph.D.’s
When abbreviating units of measurement, follow these guidelines:
Do not abbreviate common units of measurement, such as inches, pounds, feet, centimeters, and meters, unless space conservation is an overriding concern.
You may use abbreviations within tables, for example.
Do not use the # symbol to indicate “pound” or “number,” a single quotation mark (’) to indicate “foot,” or a double quotation mark (“) to indicate “inch.”
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 a megabyte. Avoid this confusion by consistently spelling out a term like “megabyte” or by using the less-abbreviated form, “Mbyte.”
Do not add “s” for the plural of units of measurement.
Abbreviations for units of measurement already account for plurals.
For example, the abbreviations for 1 kilowatt and 10 kilowatts are written the same way: kW.
Use periods in abbreviations of units of measurement that look like words.
in. for inch
oz for ounce, lb for pound (because “oz” and “lb” are not words)
Leave a space between a numeral and an abbreviation unless the industry standard for a particular unit of measurement does not include a space or unless the abbreviation resembles a word.
12 mm
220V, 10A
Include the metric or U.S. equivalent of a unit of measurement when appropriate.
1 in. (2.54 cm)
0.45359 kg (1 lb)
This section reviews basic punctuation rules and guidelines for American English, notes exceptions, and suggests alternatives. The section is organized alphabetically.
Note
Note — Traditional punctuation marks have specialized meanings in the context of programming languages. A classic example is that of quotation marks in the C shell or Bourne shell. These shells have specialized, nonintuitive meanings for single quotes, double quotes, and back quotes. Watch for these types of specialized usages in your writing and editing.
Use an apostrophe in the following situations:
In contractions. Use an apostrophe to replace letters that are omitted in a contraction.
can’t
isn’t
In place of numerals. Use an apostrophe to replace omitted numerals. Use this informal construction sparingly.
Class of ’66
Technology of the ’90s
For possessives. Use an apostrophe to denote the possessive case of a noun.
Add an apostrophe and an “s” to most indefinite pronouns, singular nouns (including collective nouns), and plural nouns that do not end in “s.”
the manager’s responsibilities
someone’s system
the group’s privileges
people’s rights
To form the possessive of singular nouns ending in “s” or its sound, you often add an apostrophe and an “s.”
the mouse’s buttons
the bus’s capacity
Add only the apostrophe when the addition of an “s” produces an awkward sound.
Plirg Systems’ employees
In a few cases, however, either is acceptable.
M. Travis’s files
M. Travis’ files
Add an apostrophe to form the possessive of plural nouns that end in “s.”
the Travises’ files
the boards’ interrupts
Add an apostrophe and an “s” to the last word of a compound to form the possessive of most compound constructions.
each other’s files
anyone else’s business
The possessive of two or more names depends on ownership. In the first example, ownership is joint. In the second example, ownership is individual.
Malcolm and Mary’s files
Malcolm’s and Mary’s files
To form plurals. Use an apostrophe to form the plurals of most numerals and symbols, lowercase letters, and single uppercase letters.
Use an apostrophe to form the plurals of abbreviations and acronyms that use internal periods.
P’s and Q’s
~’s and #’s
1’s
Ph.D.’s
The apostrophe is not necessary, although not incorrect, when you are forming the plural of two or more unitary uppercase letters or numerals.
CPUs
user IDs
operating system of the 1990s
Single lowercase letters and single uppercase letters are awkward in the plural possessive form. Rewrite to avoid this problem.
Brackets are not substitutes for parentheses. To preserve their unique service as meaningful signals to your readers, construct sentences in a way that minimizes the grammatical need for brackets.
Use brackets in the following situations:
Within parenthetic text. Use brackets to insert a parenthetic word or phrase into material that is already enclosed by parentheses.
Placing comments within a menu file often makes sense. (See page 154 of Advanced Skills, Revision A [May, 1991] for related information.)
In optional command-line entries. Use brackets to set off an optional part of a command line.
date[yymmddhhmm]
The following sections describe appropriate use of a colon.
Use a colon in the following situations:
To introduce a list. When introducing a list, use a colon if the introduction is clearly anticipatory of the list, especially if the introduction contains phrasing such as “the following” or “as follows.”
Default settings include four secondary groups:
operator,devices,accounts, andnetworks.The following options are available from the Diagnostics menu:
Test Computer
Inspect Computer
Upgrade Software
If the introduction is complete in itself, use a period. See “Capitalizing and Punctuating Lists” on page 39for other guidelines to use when punctuating lists.
Ensure that any introductory text that ends in a colon is a complete sentence or a noun phrase. Avoid sentence fragments for introductory text that ends in a colon.
Incorrect:
For example, in your startup script, set:
Correct:
For example, in your startup script, set the following parameters:
When the introduction to steps in a procedure is a complete sentence, the use of a colon is optional. If numbered steps immediately follow the statement, you can generally use a colon. If numbered steps do not immediately follow the statement, use a period.
Learn how to send a message by following these steps:
Follow the steps in this section to send a message.
Before explanatory text. Use a colon to indicate that the initial clause will be further explained or illustrated by information that follows the colon.
The colon serves as a substitute for phrases such as “in other words,” “namely,” or “for instance.”
Notice in the next example that the first word following the colon is capitalized. Capitalize the first word of the statement if the statement is a complete sentence. Do not capitalize the first word if the statement is a sentence fragment.
This software project was bad from the start: Customer requirements were never defined, management was not committed to the project, and the deadlines were unrealistic.
After an introduction. Use a colon after an introduction to a statement or question.
Here is the choice: Do you want to save the file or delete it?
Remember this cardinal rule: Never reboot your system until you have saved all of your files.
Before “for example” and similar expressions. Use a colon before expressions such as “for example,” “that is,” and “namely” when the expression causes a major break in the flow of the sentence.
Take precautions to preserve your data: For example, the best precaution that you can take is to save your files often.
With the name of a disk drive. Use a colon after the name of a specific disk drive.
Insert the diskette into drive A: and press Return.
Do not use a colon in the following situations:
To introduce a figure or a table.
Figure 3-2 shows the relationship between servers and clients.
Table 4-7 lists the features and their corresponding UNIX ® commands.
The following figure shows the parts of the editing window.
When referring to screen elements in text. When a field name, menu option, or any element on the screen is followed by a colon, omit the colon in text.
The Printers menu (even though the on-screen label is “Printers:”)
The Hosts option (even though the on-screen label is “Hosts:”)
To introduce headings.
Incorrect:
<Level2Head>Preinstallation Checklist
Before you begin the installation, verify several things about your system:
<Level3Head>Check the Configuration
Correct:
<Level2Head>Preinstallation Checklist
Before you begin the installation, verify several things about your system.
<Level3Head>Check the Configuration
At the end of a procedure heading.
Incorrect: To Configure Your System:
Correct: To Configure Your System
In a list that is introduced by “includes” or “are” within a sentence.
Incorrect:
The base colors that are used in four-color printing are: cyan, magenta, yellow, and black.
Correct:
The base colors that are used in four-color printing are cyan, magenta, yellow, and black.
The following sections describe appropriate use of a comma.
Use a comma in the following situations:
In a series. Use commas to separate the items in a series of three or more words, phrases, or clauses.
Among your hidden files are
.cshrc,.defaults,.login, and.mailrc.
Using a comma before the conjunction that joins the last two items in a series prevents confusion regarding whether the last two items in a series are related.
The following sentence is confusing because the final job opening could be read as a single field (“advertising and public relations”).
Current job openings include positions in programming, technical writing, advertising and public relations.
If an independent clause already contains a comma, consider using a list to separate the items in a series.
Incorrect:
The window has a menu bar, which lists available menus, a palette, which shows graphics tools, and a working area, where you draw.
Correct:
The window contains the following items:
Menu bar, which lists available menus
Palette, which shows graphics tools
Working area, where you draw
To separate independent clauses in a sentence. Use a comma to separate independent clauses that are joined by the coordinating conjunctions “and,” “but,” “yet,” “for,” “nor,” and “or.”
Place the comma before the conjunction.
You do not have to back up your files, but doing so is prudent.
She lost all of her work, yet she still does not back up her files.
To separate a subordinate clause or long introductory phrase at the start of a sentence from the main clause.
If you have not deleted a marked file, you can restore it.
Using a text editor, change the last line of the file.
After a dependent adverbial clause or prepositional phrase that starts a sentence.
By recording transactions and automating billing, the financial software saves time and prevents costly errors.
In such cases, hosts assume that destinations are not accessible.
Do not include the comma if the phrase appears in its normal order in the sentence.
Because this feature automatically updates system files, it saves time.
This feature saves time because it automatically updates system files.
To separate an introductory modifier from the rest of the sentence.
Hopefully, he entered the personnel office.
Confident that she had saved her work, she logged out.
With nonrestrictive phrases. Use a comma to set off nonrestrictive clauses or phrases.
The mail icon, which looks like a mailbox, flashes.
Writers often refer to this book, which is a style guide for the computer industry.
With parenthetic text. Use commas to set off short parenthetic material.
The software, with its simple interface, decreases input time by 50 percent.
In addresses. Use commas to set off components of an address when the address appears in a sentence or on one line.
Write to Plirg Systems, Inc., North Bay Village, Florida.
With appositives. In most cases, use commas instead of dashes to set off a single appositive.
The monitor, hardware that looks like a television set, has only one function.
In dates. Use commas to separate components of a date.
The comma is optional, however, with only two components.
She was hired on January 1, 1996, and left six months later.
She was hired in January 1996.
With “for example” and similar expressions. Use commas to set off expressions such as “for example,” “that is,” and “namely.”
Enter the date in MMDDYY format, for example, 110798.
Precede such expressions with a comma only for minor breaks in continuity. For major breaks in continuity, divide the sentence into two sentences.
Incorrect:
The database lists existing objects; however, it does not include objects created since the previous session.
Correct:
The database lists existing objects. The database does not include objects created since the previous session.
Do not use a comma in the following situations:
In a series of adjectives that is used as one modifier.
Click the small black button at the top of the window.
Between two short independent clauses.
Back up your work or you are fired.
Save your changes and quit the text editor.
If a dependent adverbial clause or prepositional phrase appears in its normal order in the sentence.
Because this feature automatically updates system files, it saves time.
This feature saves time because it automatically updates system files.
Using an em dash for explanatory purposes can result in sentences that are difficult for readers to understand because the sentences contain more than one main idea. When possible, divide a sentence in which em dashes are used for explanatory purposes into two sentences.
Incorrect:
After a context is established between two peers—say, a client and a server—messages can be protected before being sent.
Correct:
After a context is established between two peers, messages can be protected before being sent. An example of two peers is a client and a server.
Em dashes are sometimes used before and after an appositive series.
Three vital pieces of hardware—the keyboard, the system unit, and the monitor—are packed in the largest carton.
Use an en dash in the following situations:
To indicate ranges. Use an en dash, without surrounding spaces, to indicate a range.
Refer to pages 16–24.
Place the machines 12–16 inches apart.
However, if a book uses chapter-by-chapter page numbering, use the word “to” to indicate a page range.
Refer to pages 2-15 to 2-19.
To indicate negative numbers. Use an en dash as the minus sign for numbers that are less than zero.
Do not operate this equipment in temperatures lower than –10° C.
In lists. In a bulleted list, you can use an en dash to separate an introductory word or phrase from its explanation.
When you use this list format, put a space before and after the en dash. If the text following the introductory word or phrase is extensive, use a period instead of an en dash.
The word processing software includes the following features:
Automatic save—. Saves changes every two minutes
Automatic backup—. Creates a backup file when you exit
Automatic recall—. Tracks the last 20 transactions
In table, figure, and example numbers. Most authoring tools automatically provide the table or figure number in table and figure cross-references.
If you have to type a table or figure number, use an en dash between the two numbers.
Ellipsis points are made up of three dots. Avoid the use of ellipsis points except when showing truncated text within a code fragment. Do not include the ellipsis points shown in a menu item when mentioning the item in running text.
Do not use exclamation points except where they have some technical significance. For example, the ! operators in programming and scripting languages have technical meaning.
Incorrect: Configure the system manually!
Correct: Configure the system manually.
Because the computer industry has developed unique terminology, the use of hyphens has become troublesome. Computer documents are often littered with unnecessary hyphens. As a general rule, hyphenate a multiword expression that is used as a modifier. Do not hyphenate a multiword expression that is used as a verb or noun.
the check-in procedure | check in the material |
the direct-access password | if you have direct access |
the end-user application | writing for end users |
the look-up table | look up the definition |
Use a hyphen in the following situations:
In compound modifiers. With some exceptions, use a hyphen to form a compound modifier when the modifier is used before the noun.
An exception is open compound nouns used as modifiers, as described in “When Not to Use a Hyphen” on page 25.
Review the context-sensitive help.
This menu-driven application provides all possible options.
Use hyphens with numerals in compound modifiers.
Print the 500,000-byte file.
Note the difference in meaning between “end-user control” and “end user control.” If you do not intend to abolish the user’s control, use a hyphen to avoid ambiguity.
Hyphenate a compound modifier when it appears before a noun. When a modifier appears after a noun, do not hyphenate a compound modifier.
An easy-to-remember mail alias is a person’s first initial and last name.
A mail alias that is easy to remember is a person’s first initial and last name.
To prevent ambiguity. Use a hyphen to clarify ambiguous text.
Ed owns a small-doll shop.
Ed owns a small doll shop.
He recovered the sofa.
He re-covered the sofa.
With some prefixes and suffixes. Use a hyphen in most cases between a prefix or suffix and a root word when the combination results in double letters.
re-enable
co-organizer
shell-like
When in doubt, use the guidelines in a standard dictionary. For example, the following words do not use the general rule:
reentry
unnumbered
misspell
Use a hyphen to join numbers and proper nouns or modifiers with the following prefixes. However, these prefixes are usually joined without hyphens to common nouns and modifiers.
mid-
neo-
non-
pan-
pro-
un-
Almost without exception, hyphens join the following prefixes with the main word of a compound:
all-
ex-
self-
With two words that precede and modify a noun as a unit if one of the words is a past or present participle. A participle functions as an adjective and is formed by the addition of “-ing” (present participle) or “-ed” (past participle).
file-sharing protocol
write-protected device
user-defined functions
In fractions. Use a hyphen to separate the components of a spelled-out fraction.
The resulting file will occupy nearly one-third of your disk.
In key combinations for some product lines. Unless the platform that you are documenting indicates another style, use a hyphen to join simultaneous keystrokes.
Control-A
Ctrl-Shift-Q
Meta-A
For more information about punctuation for key combinations, see “Documenting Multiple Keystrokes” on page 62.
In variable names. Use a hyphen to separate words of a variable name that is two or more syllables long except userid, username, and other variable names that are short and easy to read as one word.
Do not use a space or underscore in variable names. Reserve underscores for their designated use in code.
directory-name
system-name
hostname
mount-options
Do not use a hyphen in the following situations:
For industry-accepted terms. Do not hyphenate compound words that are generally accepted as single words.
online
database
email
To construct nouns. Do not hyphenate two words that are used as a noun even if those same words are hyphenated when they are used as a compound modifier.
Writing documentation for end users is different from writing the end-user application.
If you have direct access, you can use the direct-access password.
To construct verbs. Do not hyphenate two words that are used as a verb even if those same words are hyphenated when they are used as a compound modifier.
Check in the book only after reading the check-in instructions.
Look up the value in the look-up table.
With open compound nouns used as modifiers. Do not hyphenate open compound nouns used as modifiers except to avoid ambiguity or to comply with industry standards, such as the terms “cathode-ray tube” or “CD-ROM drive.” An open compound noun is a combination of separate nouns that are so closely related as to constitute a single concept. When using open compound nouns, do not create noun strings longer than three words.
data interchange format
device driver interface
disk storage device
domain name address
file name extension
file server specifications
For more information, see “Use Modifiers and Nouns Carefully” on page 141.
With a compound modifier (adverb) ending in “ly.”. Never hyphenate a compound modifier that includes an adverb that ends in “ly.”
An easily remembered mail alias is a person’s first initial and last name.
By itself in suspended form. When you have successive compound adjectives with a common component, do not omit the component and leave the hyphen suspended.
Incorrect: 8- and 7-bit characters
Correct: 8-bit and 7-bit characters
With numerals as single modifiers. Do not hyphenate numerals or numbers when they serve as single modifiers.
The file requires 500,000 bytes of disk space.
With some prefixes. Do not hyphenate a word that is listed as unhyphenated in a standard dictionary and that uses a common prefix.
bi-
multi-
pre-
inter-
non-
sub-
meta-
over-
un-
micro-
post-
under-
mini-
To indicate a range. Use an en dash (with no space before or after it) instead of a hyphen to indicate a range.
Refer to pages 16–24.
Place the machines 12–16 inches apart.
However, if a book uses chapter-by-chapter page numbering, use the word “to” to indicate a page range.
Refer to pages 2-15 to 2-19.
With trademarked terms. See “Proper Use of Trademarks” on page 157 for exceptions.
Avoid parenthetical statements that distract from the main idea of a sentence. Consider rewriting a sentence that contains a parenthetical statement as two sentences. If the parenthetical statement is a definition, move the term and text to a glossary and create a cross-reference.
Incorrect:
The configuration file that is created by Create Action is written to home-directory/
.dt/type/action-name.dt. Theaction_file(the executable file with the same name as the action) is placed in your home directory.Correct:
The configuration file that is created by Create Action is written to home-directory/
.dt/type/action-name.dt. Theaction_fileis placed in your home directory. Theaction_fileis the executable file with the same name as the action.
Note
Note — Do not use “(s)” after nouns to indicate singular or plural. Either use the plural alone or insert the phrase “one or more” before the plural.
Use parentheses in the following situations:
In lists. Use either two parentheses or one parenthesis to set off letters or numerals that designate items that are listed within a sentence.
Choose from (a) keyboard entry, (b) mouse entry, and (c) voice entry.
Choose from a) keyboard entry, b) mouse entry, and c) voice entry.
To enclose an entire sentence. Parenthetical sentences can occasionally hinder clear writing by causing the reader to pause. Where possible, consider rewriting a parenthetical sentence without the parentheses. Occasionally, you might want to use parentheses to enclose an entire sentence that is relevant to information presented in the paragraph, yet dispensable to the paragraph’s meaning. When an entire sentence is enclosed in parentheses, place the final parenthesis after the sentence’s final punctuation mark.
Whole paragraphs should never be parenthetic.
Position the pointer on the top scrollbox and click the left mouse button. (For detailed instructions on scrolling windows, see page 586.)
With first occurrences. Use parentheses to enclose special keyboard symbols, abbreviations, and acronyms when they first appear in text.
The operating system inserts a tilde (~) when a file name is too long.
The software package tracks maintenance on your heating, ventilating, and air conditioning (HVAC) systems.
When providing the metric equivalent of a U.S. measure.
3 in. (76.2 mm)
Use a period in the following situations:
To end a sentence. Use a period to end a declarative or imperative sentence.
Computer documentation is always grammatically precise.
In file and directory names. Use a period as part of a file name to separate the file name from a file extension.
When used in technical terms, a period is called a “dot.”
The procedures are in the
howto.docfile.The
ls -acommand lists.cshrcand.orgrcamong your hidden files.
In the UNIX operating system, a period also serves as an abbreviation for the current directory.
To copy a file into the current directory, you would type the following command:
cp ~/work/budget .
With abbreviations. A period is used with some abbreviations, and always with those abbreviations that would look like a word otherwise.
a.m.
U.S.
In lists. In a bulleted list, you can use a period to separate an introductory word or phrase from its explanation. If the text following the introductory word or phrase is brief, use an en dash instead of a period.
Use quotation marks in the following situations:
For quotes. Quotation marks indicate that material was taken verbatim from another source.
Do not enclose verbatim commands, system messages, file names, and so forth in quotation marks. In some cases, a reader can be misled into thinking that the quotation marks are an integral part of text that is to be typed.
For multiple-paragraph quotations. If the quotation has multiple paragraphs, put an open quotation mark at the beginning of each paragraph and a final quotation mark at the end of the last paragraph.
If the paragraphs are indented as a block quotation, do not use any quotation marks.
Around chapter titles and section headings. Use quotation marks to enclose titles of chapters and headings of sections in a book.
“Sending Mail” on page 42 describes how to send an email message.
For emphasis. Use quotation marks to emphasize a word or phrase when it is used in an uncommon way or when it is the subject of discussion.
Use the
teecommand to take a “snapshot” of your keystrokes.The word “menu” is often used in technical writing, but not the word “restaurant.”
Around single letters. Use quotation marks to surround single letters.
The letter “x” denotes the version number.
No single rule governs the placement of quotation marks that are next to other punctuation marks. Whether the final quotation mark follows or precedes another punctuation mark depends on context, as explained here:
With commas and periods. Place the final quotation mark after commas and periods, no matter how long or short the quoted material is.
“Yes,” he replied, “the program is written.”
With colons and semicolons. Place the final quotation mark before a colon or semicolon unless the colon or semicolon is part of quoted text.
Remember the cardinal rule for taking a “snapshot”: Use the recommended palette.
With question marks. Place the final quotation mark after a question mark when the question is part of the quoted material.
The system prompts, “Do you want to continue?”
The user’s guide answers the question, “What can I do with this product?”
Place the final quotation mark before a question mark that is not part of the quoted material.
How do I display a list of files that are “hidden”?
Avoid using semicolons. Semicolons are often misused and are difficult to read online. For conjoined sentences, consider rewriting the text as separate sentences.
Incorrect:
The redirects contain the link-layer address of the new first hop; separate address resolution is not necessary.
Correct:
The redirects contain the link-layer address of the new first hop. Separate address resolution is not necessary.
Semicolons are sometimes used to separate short independent clauses joined by conjunctive adverbs such as “however” or “therefore.”
Both methods are acceptable; however, the direct access method is preferred.
For serial semicolons, consider rewriting the text as a vertical list.
Incorrect:
The Reply menu provides the following options: Reply (all), include; Reply, include; Reply (all); and Reply.
Correct:
The Reply menu provides the following options:
Reply (all), include
Reply, include
Reply (all)
Reply