2 STYLE AND PUNCTUATION

This chapter discusses the writing style and punctuation used in manuals written by Hawley & Associates. It is divided into two main parts:

	Writing style
	Punctuation Marks

2.1 Writing Style

Hawley & Associates manuals are expected to be accurate, complete, easy to read, and timely. All manuals should be written in a friendly way. They should not, however, become folksy or humorous in an attempt to become friendly. Strive for a conversational tone without using technical jargon. Always use second person, active voice whenever possible. There may be some occasions that require you to use the third person, but when you do this, be sure to include the doer of the action.

Another way to achieve friendliness and also clarity is to avoid wordiness. Phrases like in order can be shortened to to, for example. Writing in second person can cut out as much as 20 to 30% of the words in a manual.

Manuals should not be boring to the reader. try to always use active verbs and as few words as possible. For example, the word use comes up quite often in manuals. You could replace the word use with manipulate, apply, or operate.

2.1.1 Chapter Titles

When you create a new chapter or divide the information presented in some way, you generally start that section with a title. Titles enhance the information, making it easy for the reader to reference it. Titles should be explicit about the information to be found in that section and should indicate the scope and intent of the section. Here are two examples:

2.1.2 Organizing Topics

Good manuals are focused and flow logically. While it may be clear to you how a manual is organized, it won't always be so clear to your reader. Always be sure that you have a logical organization in your manual and that you carefully explain it to your readers. This helps them follow your flow and helps you stay focused on your topic.

Topic sentences are another way to keep your readers interested in your material. All paragraphs should have topic sentences. The rest of the paragraph should develop the topic logically and smoothly. Good writing is not just a set of well constructed paragraphs, but those paragraphs should flow smoothly.

Flow between paragraphs is also very important. Often, a reader will wonder why a topic is introduced suddenly. This usually means the reason for moving from one topic to another was not made clear with words like therefore or on the other hand or some other like phrase; in other words there is very little or no flow between paragraphs.

Writing in parallel should also be followed especially when writing lists. Parallel writing means when you state one instance, all following instances should be stated in the same way. For example:

Parallel writing helps to lead the reader along and keeps them interested in the topic being discussed.

Always write a manual in present tense. The computer does this, not the computer will do this. Future tense sounds vague and dependent. If you must use another tense, be sure it is valid. Do not change tense in the same sentence.

2.2 Punctuation

This section lists basic punctuation rules and guidelines. Note that traditional punctuation marks can take on specialized meanings when documenting programming languages. For example, quotation marks in the C or Bourne shell, which provide specialized meaning for single, double and back quotes.

2.2.1 Apostrophes

The apostrophe is used to show possession and to mark the omission of letters. Use an apostrophe in the following cases:

• In contractions. Apostrophes replace omitted letters. For example, can't, aren't, and it's.
• In place of numerals. Apostrophes replace omitted numerals. For example, Spirit of '76, Class of '94.
• For possessives. Use apostrophes to note the possessive case of nouns. If a noun does not end in 's,' add an apostrophe and an 's' to most indefinite pronouns, singular nouns and plural nouns. For example, the file's properties and women's rights. To form the possessive of a singular noun ending in s (or its sound), add an apostrophe and an &'s' to it. For example, the mouse's buttons or the bus's capacity.

If the addition of an 's' produces an awkward sound, add only the apostrophe, as in Stevens Systems' Employees. Add an apostrophe to form the possessive of plural nouns that end in 's,' as in Mr. Andrews' files. The possessive of two or more proper nouns depends on ownership. For example, John and Yoko's files indicates joint ownership, while John's and Yoko's files indicates individual ownership.

Use apostrophes to form the plurals of most numerals and symbols, lowercase letters, or single uppercase letters. For example: drive B's and -f's.

The apostrophe is not necessary (although not incorrect to use) when you are forming the plural of two or more unitary uppercase letters or numerals.

2.2.2 Brackets

Brackets are not substitutes for parentheses. Brackets should not normally be used, except for the following cases:

• With parenthetic text. Use brackets when inserting a parenthetic word or phrase into text already enclosed in parentheses, For example: According to Time magazine, (page 14 of May, 1996 [Volume 1]), 90% of Canadians think DB Cooper is still alive.
• In Optional command-line entries. Brackets can set off an optional part of a command line. For example: date [yymmdd]

2.2.3 Colons

The colon lets the reader know there is a close connection between the first statement and the one immediately after it. A colon can also be used to connect a list or series to the clause, word, or phrase with which it corresponds to. For example:

Do not place a colon between a verb and its objects. For example, the statement "The three fluids for cleaning metal are: acetone, alcohol, and water." should be changed to "The three fluids for cleaning metal are acetone, alcohol, and water." Do not place a colon between a preposition and its object.

A colon can be used to link one statement to another that develops or explains the first. For example: "Any large organization has two main informational problems: it should maintain an effective internal communication system, and it must insure that an effective communication system is maintained at all times."

The first word after a colon may be capitalized if the statement following it is a complete sentence or it introduces a formal resolution or question.

2.2.4 Commas

The comma helps readers understand the meaning of your words and prevents ambiguity. There are numerous instances where commas should be used. Use the serial comma for lists of items. Notice in the example shown below, there is a comma after the word and.

Use a comma between independent clauses that are linked by a coordinating conjunction, or to separate two main clauses in a compound sentence (and, but, or, not, and sometimes so, yet, and for). Example:

Here is a list of common cases where commas are used:

To separate a list of items. Use a comma between three or more items, including before the and.

To separate two or more adjectives. Use a comma to separate two or more adjectives that modify the same noun, as in "We need an exciting, hard-hitting ad campaign."

To separate numbers. Use a comma to separate the hundreds-place in numbers greater than 9999.

To indicate omission. Use a comma to indicate an omitted word, as in "Half the purchase price is due on delivery of the goods, the balance in three months."

To indicate full stops. Use a comma to indicate a full stop, as in "What will happen, we don't know."

After introductory elements. Use a comma to separate an introductory element that comes before the subject and verb of the main clause, as in "When I return to the office, I will get back to you."

After introductory requests or commands. Use a comma in these cases: "Look, we've been through this before," and "Established in 1974, the firm grew swiftly to over 500 people."

Use commas after introductory adverbs and phrases when they function as transitional expressions (well, therefore, however) and when they function as independent comments (in my opinion, by all means, obviously)

You should always include the command after a last word in a series. It makes the statement clearer and the presence of the comma reduces ambiguity.

Do not use a comma after introductory adverbs or short introductory phrases.

Do not separate a subject and a verb.

Do not separate a verb and its object of complement: "She is honest, hard-working, and extremely capable."

Do not separate an adjective and a noun.

Do not separate a noun and a prepositional phrase that follows, as in: "The board of IBM will announce this new product."

Do not separate a coordinating conjunction and the following word, as in "You can read it now/ or when you get home."

Do not separate two items joined by a coordinating conjunction, as in "We hope that you will visit our store soon and/that you will find the style you like."

2.2.5 Contractions

A contraction is a shortened spelling of a word or phrase with an apostrophe substituting for the missing letters. Here are some rules for using contractions:

• Don't overuse them.
• Avoid obscure contractions and nonstandard usages and regionalisms, like mustn't or shan't; or using ain't and don't to mean does not.
• Never create your own contraction.
• Use "it's" correctly. "It's" is the contraction of "it is." "Its" is the possessive of it.
• Use "you're" correctly. "You're" is the contraction of "you are." "Your" is a possessive adjective.

2.2.6 Dashes

The dash is versatile because it can link, separate and enclose a clause. However, it also can be limited because it can easily be overused. Use dashes cautiously to indicate more informality or emphasis than would be achieved by other punctuation marks.

A dash can emphasize a sharp turn in thought, as in "The project will end January 15—unless we get more capital." A dash can indicate an emphatic pause, as in "We will start the software project; after Windows98 is installed." A dash can also be used with but to emphasize contrast, as in "We can produce work more quickly; but the end result will not be as good."

There are two types of dashes used in Hawley & Associates manuals: Em dashes and En dashes. Em dashes usually are a long dash and are used when you need to mark a sharp break in a sentence and a comma doesn't provide the emphasis you want (see the example in the previous paragraph for an example of an em dash). En dashes on the other hand are a shorter dash on the other hand are used to indicate a range, such as "See pages 16-25." Or to indicate negative numbers, such as a minus sign for numbers less than zero, such as "Do not operate this equipment in temperatures lower than -20 degrees C."

Remember too when using dashes to never leave a space before or after the dash.

2.2.7 Ellipsis Mark

An ellipsis mark is used to note an omission of quoted material in text. It is made up of three ellipsis points (periods) with a space between each point. One space separates the ellipsis mark from text before and text after the point where the mark is located.

Use an ellipsis mark for the following:

• For omissions. An ellipsis mark shows that text has been omitted from a sentence, phrase, or clause. Example: "The system displays: "Do you want . . . menu choices now?"

• For pauses. Use an ellipsis mark to indicate a pause when quoting a displayed message. Example: "System loading. Please wait . . ."

2.2.8 Hyphens

Using hyphens has become troublesome because the computer field has developed so many unique terms. As a general rule, hyphenate a multiword expression when it is used as a modifier, and do not hyphenate it when it is being used as a verb or a noun.

Here are some general rules to follow in using hyphens. Use a hyphen:

• With compound modifiers. Generally, use a hyphen to form a compound modifier when the modifier is used before the noun. Use hyphens with numerals in compound modifiers. Example: Here is the 2,000-byte file or This applies to read-write operations.

• To prevent ambiguity. Hyphens help clarify ambiguous text. Example: Robert runs a car-repair store as opposed to Robert runs a car repair store.
• With prefixes and suffixes. A hyphen is often used between a prefix and suffix and a root word when the combination results in double letters. Words like re-enable, co-organizer, and shell-like fit under this category. However, not all prefixes and suffixes fall under this category; follow the guidelines found in a standard dictionary if you have a question about a word.

• In fractions. A hyphen separates the components of a spelled-out fraction. Example: Writing the code for the Java program will take up one-fourth of the project time.
• In key combinations. Use a hyphen to separate key combinations. Example: Press Control-Shift-R.

Do not use a hyphen in the following cases:

• For industry-accepted terms. Do not hyphenate compound words that are now widely accepted, like backup and database.
• To construct verbs. Do not hyphenate two words that are used as a verb, but that are hyphenated when used as a compound modifier. Example: Log on only after reading the dial-up instructions.
• With a compound modifier (adverb) ending in '-ly.' Do not hyphenate a compound modifier that includes an adverb that ends in '-ly.' Example: "An easily remembered password is probably not safe to use."
• With numerals as single modifiers. Do not hyphenate numerals or numbers when they serve as single modifiers. Example: "This file contains 200,000 bytes."
• With some prefixes and suffixes. Do not use a hyphen in a word that is listed as unhyphenated in a standard dictionary and that uses a common prefix.

• To indicate a range. Use an en dash instead of a hyphen to indicate a range. Do not put a space either before or after the dash. Example: ‘Refer to pages 16-24."

Note: Some word processing and authoring tools support automatic hyphenation of words if they break at the end of a line.

2.2.9 Parentheses

Parentheses are used to enclose words, phrases, and sentences. If you feel you need to use them, consider if the parenthetic material is important enough to be included at all. If so, it may fit better without parentheses within the paragraph. If not, don&'t include it. Use paragraphs in these cases:

• With digressive text. Use parentheses to enclose relevant material that should not be part of the main sentence, either because it would be confusing if punctuated otherwise or because it is digressive. Example: "The font menu, which provides four options (Regular, Bold, Italic, Underlined) is easy to use."
• For elaboration. Parentheses enclose material that further explains an element of the main sentence, but is not critical to that sentence&'s meaning. Example: "To keep the printer from printing supplementary information (especially when printing multiple copies of a document), check the box in the Printer window."
• In lists. Use parentheses to offset letters or numerals that designate items listed within a sentence. Example: "Choose from a) keyboard entry, b) mouse entry, or c) voice entry.
• With first occurrences. Parentheses enclose special keyboard symbols, and abbreviations and acronyms when they first appear in text. Example: "The operating system inserts a tilde (~) when a file name is too long."

2.2.10 Periods

A period usually indicates the end of a sentence. Use them in the following cases:

• In file and directory names. A period is sometimes part of a file name (separating a file name from a file extension). Example: "The instructions are in the README.DOC file. In the UNIX system, a period also serves as an abbreviation for the current directory, as shown here: "To copy a file into the current directory, type cp ~/work/budget .
• To end a sentence. Use a period to end a declaritive or imperative sentence. Example: "Computer manuals are always precise."

• With abbreviations. A period follows some common abbreviations. Example: "The meeting starts at 10 a.m. on Tuesday."

2.2.11 Quotation marks

Quotation marks are used to enclose spoken or written material and should not be used to emphasize. Use them in the following cases:

• For quotes. Quotation marks indicate that the material (other than computer commands, system messages, file commands, etc.) was taken directly from another source. Do not enclose computer or file commands, system messages and related text in quotation marks, unless the marks are part of the command. The reader may think the quotation marks are part of that specific command or message. Example:

• For chapter titles. Use quotation marks to enclose titles of chapters in a book. Example:

• For highlighting. Quotation marks highlight a word or phrase when it is the subject of discussion or it is used in an unusual way. Example:

• Around single letters. Quotation marks also surround single letters. Example:

There is no single rule governing the placement of quotation marks that are next to other punctuation marks. Whether the final quotation marks follow or precede another punctuation mark depends upon context. Place the final quotation mark after most adjacent punctuation marks, no matter how long or short the quoted material is. Example: "Yes," he said, "the file has been downloaded."

Always place the final quotation mark before a colon or semicolon. Example: There are three buttons on the "mouse": left, middle, and right. Place the final quotation mark after a question mark or an exclamation point when the question or exclamation is part of the quoted material. Example: The system will now prompt you, "Do you wish to save or delete the file?"

Be sure to place the final quotation mark after the question mark or exclamation point. An example of this is "How do I save a file to CD-ROM?"

Note: Most examples in this guide have quotes at the beginning and end of the example. This section leaves them deleted, to avoid confusing the reader.

2.2.12 Semicolon

Use a semicolon between closely related and evenly balanced complete sentences. Also use a semicolon in the following cases:

• Before explanatory statements. Use a semicolon before a phrase that introduces an explanatory or summarizing statement. Example:

• With independent clauses. Use a semicolon to separate independent clauses joined by conjunctive adverbs, such as hence, however, or therefore. Example:

• In a series. A semicolon separates items in a series when the items themselves include commas. Example: The Reply button provides the following options: Replay (all), include; Reply, include; Reply (all) and Reply.