Mechanics of Writing 英文写作过程

Mechanics of Writing

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 twofile’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 Chapter2for options

related to the use of text and graphical elements,such as section headings,tables,and

cross-references.

This chapter discusses the following topics:

I“Capitalization”on page2

I“Contractions”on page4

I“Gerunds and Participles”on page5

I“Numbers and Numerals”on page6

I“Pronouns”on page10

I“Technical Abbreviations,Acronyms,and Units of Measurement”on page11

I“Punctuation”on page14

1Capitalization

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 yourfile.

Use Text Editor to change the information in yourfile.

In thefirst 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–See Chapter13and Chapter14for 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 page328in Appendix D for suggested

resources.

What to Capitalize

Capitalize the following items:

I Proper nouns

I The letters of many abbreviations and acronyms

I Thefirst letter of thefirst word in numbered or bulleted lists

I Thefirst letter of thefirst word infigure callouts(see“Writing Callouts for

Illustrations”on page214)

2Read Me First!I Thefirst 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 Chapter3.

See Section9in the reference manual.

See the following table.

I The Roman numeral that designates the sequence of a part divider in a manual

Part III

I Thefirst letter of each term that identifies the name of a key on a keyboard

Control-A

Escape key

the M key

Ctrl-Shift-Q

I Thefirst letter of thefirst 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:format enables you to divide the disk into slices.

Correct:Use the format utility to divide the disk into slices.

I Thefirst letter of thefirst 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.

I Thefirst letter of thefirst word in a title or heading,thefirst 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 page11.

How to Delete Text With the Cut Function Key

I Thefirst 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

I Figure captions,example captions,table captions,and table column headings,

using the same rules as for titles and section headings

I Hardware switch names and buttons

Power-On/Off switch

Standby switch

Power button

Chapter1•Mechanics of Writing3What Not to Capitalize

Do not capitalize the following items:

I The word“page”when followed by a number

Refer to page45.

I 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)

I The“x”in hexadecimal text,as in“0x8E”

I The“x”in“x86”

I The“x”in dimensions,as in“12x12inches”

I Any word for the sole reason of emphasizing it(use italic for emphasis)

I The words“release”or“version”unless these words are part of a product name

I Variable names that are used in code examples

I Command and function names

I Words infigure callouts other than thefirst word,proper nouns,abbreviations,or

acronyms

I Thefirst word following a colon if the word begins a text fragment

This button has only one purpose:to shut down the system.

Contractions

Contractions can potentially cause confusion for localization or nonnative English

speakers.When using contractions,follow these guidelines:

I 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.

I 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.”

I Never create your own contractions.

I Avoid adding“’s”for“is”or“has”to form a contraction(for example,“that’s”).

This construction can be confused with possessive constructions.

4Read Me First!I 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”).

Gerunds and Participles

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:

I Rewrite sentences to avoid gerunds that are immediately followed by nouns.

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.

Chapter1•Mechanics of Writing5I 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 thefile 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 thefile name as a

parameter for the message.

The Document Editor uses thefile 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.

Numbers and Numerals

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.

6Read Me First!

Spelling Out Numbers

Spell out numbers in the following situations:

I 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)

3MIPS(a measurement)

XDRfits into the presentation layer(layer6)of the ISO reference model.

I Common units of time,greater than one second,from zero through nine

five minutes

three days

I Approximations

You can choose from hundreds of applications for your computer.

I The zeroes in extreme values,such as“million”and“billion,”but precede these

words with a numeral

3million instructions per second

I Any number that begins a sentence

Tenfiles are required.

I A number that is immediately followed by a numeral

Print twelve500,000-bytefiles.

Print12of the500,000-bytefiles.

Using Numerals

Use numerals in the following cases:

I Numbers10or greater

I Numbers less than10if they are of the same type and appear in the same sentence,

paragraph,or bulleted list as numbers of10or greater

The menu offers11options,but you use only4options.

I Numbers less than10if they are used in terms common to standards that are

approved by organizations such as International Organization for Standardization (ISO)

XDRfits into the presentation layer(layer6)of the ISO reference model.

I Negative numbers

I Most fractions(see“Using Fractions”on page9)

I All percentages

Chapter1•Mechanics of Writing7I All decimals,including the leading zero

0.15

1.25

I All measurements(see“Units of Measurement”on page13)

6pounds

3.5-inch disk drive

12x12feet

I Units of time smaller than one second

5milliseconds

I Bit and byte references

4bytes

8-bit color

I Chapter,section,page,step,figure,example,and table numbers

Step4

Section6.2

I Part numbers.Use uppercase Roman numerals,for example,“Part IV”

Punctuating Numbers and Numerals

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:

I Do not hyphenate numbers or numerals when they serve as single modifiers.

Yourfile contains500,000bytes.

I Hyphenate numbers or numerals in compound modifiers.

Print the500,000-bytefile.

I Do not use a comma in numerals of four digits.

1028

6000

I 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 page144.

8Read Me First!Using Fractions

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:

I Use numerals for fractions in tables and for units of measurement,but spell out

common fractions in running text.

½-inch tape drive

half the users in the test

I Use a space between a numeral and its related fraction.

8½inches

I If a fraction is used in a compound modifier,insert a hyphen between the fraction

and its unit of measurement.

8½-inch width

I Use decimals when decimals are the industry standard.

3.5-inch diskette

I 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½-inch tape drives(there are ten drives for½-inch tape)

In tables:10½-inch tape drive(the drive is for10½-inch tape)

Preferred in text:10tape drives for½-inch tape

Chapter1•Mechanics of Writing9Pronouns

Follow these guidelines for the use of pronouns:

I 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

ok prompt 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 ok prompt is displayed.

I Do not usefirst 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().

10Read Me First!Technical Abbreviations,Acronyms,

and Units of Measurement

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.

Abbreviations and Acronyms

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.

Basic Guidelines for Abbreviations and Acronyms

When using abbreviations or acronyms,follow these guidelines:

I Do not use the Latin abbreviations e.g.,i.e.,vs.,op.cit.,viz.,and etc.

I In most cases,write out the full word or phrase and enclose its abbreviation or

acronym in parentheses thefirst 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.

I Do not spell out acronyms and abbreviations that are trademarked terms.

I 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.

I 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.

Chapter1•Mechanics of Writing11I If an abbreviation or acronym is used often in a document,repeat the spelled-out

version at thefirst appearance in each chapter where the abbreviation or acronym

appears.

I 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)

I Do not shorten trademarked terms.

I 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 youfirst 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.

Punctuating Abbreviations and Acronyms

While you usually do not have to add punctuation to abbreviations and acronyms,the

following list provides a few exceptions:

I Use periods in abbreviations that look like words.

U.S.for United States

no.for number

I 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

I Add an“s”and no apostrophe to form the plural of abbreviations or acronyms that

contain no periods.

PCs

ISVs

GUIs

I Add an apostrophe and“s”to form the plural of abbreviations or acronyms that

use internal periods.

M.S.’s

Ph.D.’s

12Read Me First!

Units of Measurement

When abbreviating units of measurement,follow these guidelines:

I 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.

I 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.”

I 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.”

I Do not add“s”for the plural of units of measurement.

Abbreviations for units of measurement already account for plurals.

For example,the abbreviations for1kilowatt and10kilowatts are written the same way:kW.

I 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)

I 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.

12mm

220V,10A

I Include the metric or U.S.equivalent of a unit of measurement when appropriate.

1in.(2.54cm)

0.45359kg(1lb)

Chapter1•Mechanics of Writing13Punctuation

This section reviews basic punctuation rules and guidelines for American English,

notes exceptions,and suggests alternatives.The section is organized alphabetically.

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.

Apostrophe

Use an apostrophe in the following situations:

I In contractions.Use an apostrophe to replace letters that are omitted in a

contraction.

can’t

isn’t

I In place of numerals.Use an apostrophe to replace omitted numerals.Use this

informal construction sparingly.

Class of’66

Technology of the’90s

I 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

14Read Me First!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’sfiles

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’sfiles

anyone else’s business

The possessive of two or more names depends on ownership.In thefirst example, ownership is joint.In the second example,ownership is individual.

Malcolm and Mary’sfiles

Malcolm’s and Mary’sfiles

I 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 the1990s

Single lowercase letters and single uppercase letters are awkward in the plural possessive form.Rewrite to avoid this problem.

Chapter1•Mechanics of Writing15Brackets

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:

I Within parenthetic text.Use brackets to insert a parenthetic word or phrase into

material that is already enclosed by parentheses.

Placing comments within a menufile often makes sense.(See page154of

Advanced Skills,Revision A[May,1991]for related information.)

I In optional command-line entries.Use brackets to set off an optional part of a

command line.

date[yymmddhhmm]

Colon

The following sections describe appropriate use of a colon.

When to Use a Colon

Use a colon in the following situations:

I 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,and networks.

The following options are available from the Diagnostics menu:

I Test Computer

I Inspect Computer

I Upgrade Software

If the introduction is complete in itself,use a period.See“Capitalizing and

Punctuating Lists”on page39for other guidelines to use when punctuating lists. 16Read Me First!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.

I 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 thefirst word following the colon is capitalized.

Capitalize thefirst word of the statement if the statement is a complete sentence.

Do not capitalize thefirst 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.

I After an introduction.Use a colon after an introduction to a statement or question.

Here is the choice:Do you want to save thefile or delete it?

Remember this cardinal rule:Never reboot your system until you have saved

all of yourfiles.

I 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 theflow of the sentence.

Take precautions to preserve your data:For example,the best precaution that

you can take is to save yourfiles often.

I 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.

Chapter1•Mechanics of Writing17When Not to Use a Colon

Do not use a colon in the following situations:

I To introduce afigure or a table.

Figure3–2shows the relationship between servers and clients.

Table4–7lists the features and their corresponding UNIX®commands.

The followingfigure shows the parts of the editing window.

I When referring to screen elements in text.When afield 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:”)

I To introduce headings.

Incorrect:

Preinstallation Checklist

Before you begin the installation,verify several things about your system:

Check the Configuration

Correct:

Preinstallation Checklist

Before you begin the installation,verify several things about your system.

Check the Configuration

I At the end of a procedure heading.

Incorrect:To Configure Your System:

Correct:To Configure Your System

I 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.

18Read Me First!

Comma

The following sections describe appropriate use of a comma.

When to Use a Comma

Use a comma in the following situations:

I In a series.Use commas to separate the items in a series of three or more words,

phrases,or clauses.

Among your hiddenfiles 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 thefinal job opening could be read as

a singlefield(“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:

I Menu bar,which lists available menus

I Palette,which shows graphics tools

I Working area,where you draw

I 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 yourfiles,but doing so is prudent.

She lost all of her work,yet she still does not back up herfiles.

I 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 markedfile,you can restore it.

Using a text editor,change the last line of thefile.

Chapter1•Mechanics of Writing19I After a dependent adverbial clause or prepositional phrase that starts a sentence.

By recording transactions and automating billing,thefinancial 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 systemfiles,it saves time.

This feature saves time because it automatically updates systemfiles.

I 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.

I 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.

I With parenthetic text.Use commas to set off short parenthetic material.

The software,with its simple interface,decreases input time by50percent.

I 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.

I 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.

I In dates.Use commas to separate components of a date.

The comma is optional,however,with only two components.

She was hired on January1,1996,and left six months later.

She was hired in January1996.

I 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.

20Read Me First!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.

When Not to Use a Comma

Do not use a comma in the following situations:

I In a series of adjectives that is used as one modifier.

Click the small black button at the top of the window.

I Between two short independent clauses.

Back up your work or you arefired.

Save your changes and quit the text editor.

I If a dependent adverbial clause or prepositional phrase appears in its normal

order in the sentence.

Because this feature automatically updates systemfiles,it saves time.

This feature saves time because it automatically updates systemfiles. Dash(Em Dash)

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.

Chapter1•Mechanics of Writing21Dash(En Dash)

Use an en dash in the following situations:

I To indicate ranges.Use an en dash,without surrounding spaces,to indicate a

range.

Refer to pages16–24.

Place the machines12–16inches apart.

However,if a book uses chapter-by-chapter page numbering,use the word“to”to

indicate a page range.

Refer to pages2-15to2-19.

I 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.

I 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:

I Automatic save–Saves changes every two minutes

I Automatic backup–Creates a backupfile when you exit

I Automatic recall–Tracks the last20transactions

I In table,figure,and example numbers.Most authoring tools automatically

provide the table orfigure number in table andfigure cross-references.

If you have to type a table orfigure number,use an en dash between the two

numbers.

Ellipsis Points

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.

22Read Me First!Exclamation Point

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.

Hyphen

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

When to Use a Hyphen

Use a hyphen in the following situations:

I 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 page25.

Review the context-sensitive help.

This menu-driven application provides all possible options.

Use hyphens with numerals in compound modifiers.

Print the500,000-bytefile.

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’sfirst initial and last name.

A mail alias that is easy to remember is a person’sfirst initial and last name.

Chapter1•Mechanics of Writing23I 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.

I 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-

I 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

I In fractions.Use a hyphen to separate the components of a spelled-out fraction.

The resultingfile will occupy nearly one-third of your disk.

24Read Me First!

I 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 page62.

I 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

Note–Some authoring environments consider a hyphen to be a line-break character. However,some hyphenated terms should stay on the same line,for example,

Control-Q.Talk to your tools support person tofind out how to indicate a nonbreaking hyphen.

When Not to Use a Hyphen

Do not use a hyphen in the following situations:

I For industry-accepted terms.Do not hyphenate compound words that are

generally accepted as single words.

online

database

email

I 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.

Chapter1•Mechanics of Writing25I 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.

I 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 page141.

I 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’sfirst initial and last name.

I 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-and7-bit characters

Correct:8-bit and7-bit characters

I With numerals as single modifiers.Do not hyphenate numerals or numbers when

they serve as single modifiers.

Thefile requires500,000bytes of disk space.

I With some prefixes.Do not hyphenate a word that is listed as unhyphenated in a

standard dictionary and that uses a common prefix.

bi-inter-meta-micro-mini-multi-

non-

over-

post-

pre-

sub-

un-

under-

26Read Me First!I 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 pages16–24.

Place the machines12–16inches apart.

However,if a book uses chapter-by-chapter page numbering,use the word“to”to indicate a page range.

Refer to pages2-15to2-19.

I With trademarked terms.See“Proper Use of Trademarks”on page157for

exceptions.

Parentheses

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 configurationfile that is created by Create Action is written to

home-directory/.dt/type/action-name.dt.The action_file(the executablefile with the same name as the action)is placed in your home directory.

Correct:

The configurationfile that is created by Create Action is written to

home-directory/.dt/type/action-name.dt.The action_file is placed in your home directory.The action_file is the executablefile with the same name as the action.

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.

When to Use Parentheses

Use parentheses in the following situations:

I 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.

I 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

Chapter1•Mechanics of Writing27use 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 thefinal parenthesis after the

sentence’sfinal 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 page586.)

I Withfirst occurrences.Use parentheses to enclose special keyboard symbols,

abbreviations,and acronyms when theyfirst appear in text.

The operating system inserts a tilde(~)when afile name is too long.

The software package tracks maintenance on your heating,ventilating,and air

conditioning(HVAC)systems.

I When providing the metric equivalent of a U.S.measure.

3in.(76.2mm)

Period

Use a period in the following situations:

I To end a sentence.Use a period to end a declarative or imperative sentence.

Computer documentation is always grammatically precise.

I Infile and directory names.Use a period as part of afile name to separate thefile

name from afile extension.

When used in technical terms,a period is called a“dot.”

The procedures are in the howto.docfile.

The ls-a command lists.cshrc and.orgrc among your hiddenfiles.

In the UNIX operating system,a period also serves as an abbreviation for the

current directory.

To copy afile into the current directory,you would type the following

command:

cp~/work/budget.

I 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.

I 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.

28Read Me First!Quotation Marks

Use quotation marks in the following situations:

I 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.

I For multiple-paragraph quotations.If the quotation has multiple paragraphs,put

an open quotation mark at the beginning of each paragraph and afinal quotation mark at the end of the last paragraph.

If the paragraphs are indented as a block quotation,do not use any quotation

marks.

I Around chapter titles and section headings.Use quotation marks to enclose titles

of chapters and headings of sections in a book.

“Sending Mail”on page42describes how to send an email message.

I 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 tee command to take a“snapshot”of your keystrokes.

The word“menu”is often used in technical writing,but not the word

“restaurant.”

I 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 thefinal quotation mark follows or precedes another punctuation mark depends on context,as explained here:

I With commas and periods.Place thefinal quotation mark after commas and

periods,no matter how long or short the quoted material is.

“Yes,”he replied,“the program is written.”

I With colons and semicolons.Place thefinal 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.

I With question marks.Place thefinal 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?”

Chapter1•Mechanics of Writing29Place thefinal quotation mark before a question mark that is not part of the quoted

material.

How do I display a list offiles that are“hidden”?

Semicolon

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 newfirst hop;separate address

resolution is not necessary.

Correct:

The redirects contain the link-layer address of the newfirst 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:

I Reply(all),include

I Reply,include

I Reply(all)

I Reply

Slash

Do not use a slash in running text.Slashes can be confusing for translators due to the

multiple meanings of this symbol,which can mean“or”(“and/or”),“and or”

(“open/close”),and“divide by”(“36/6”).

Use a slash for fractions.

1/2

3/4

30Read Me First!