Cypress Media Group

If you take a technical writing workshop, the materials will address numerous areas; some are very specific while others are more general in nature. A good starting point is to look at six principles of technical writing. Reviewing these basics can provide a great platform from which we can launch forays into specific areas of interest and documentation.

1. Use Good Grammar
2. Write Concisely
3. Use the Active Voice
4. Use Positive Statements
5. Avoid Long Sentences
6. Punctuate Correctly

Principle One: Use Good Grammar

Your readers expect technical documents to be written in standard English. Certain grammatical errors can actually cause your reader to misinterpret the information. However, because technical documents must be precise and accurate, readers expect documents to be professional, polished, and flawless.

One grammatical rule to adhere to is subject-verb agreement. Note the choice of verbs below:

One employee is absent.

Two employees are absent.

This subject-verb agreement is easy to make because in each sentence, the subject is obvious: employee in the first sentence agrees with is and employees in the second sentence agrees with are . The real challenge is when the subject is not as obvious. In the following sentences, which verb would you select?

Either of the levers is clearly marked.

Either of the levers are clearly marked?

You must decide if the subject is either or levers . If you selected either as the subject and is as the verb, you made the correct choice. A list of indefinite pronouns that are always singular is listed below:

Each, either, everybody, everyone, neither, one, anyone, anybody, someone, somebody, no one, nobody

The following indefinite pronouns are always plural:

Both, few, many, several

Just to keep your life interesting, the following pronouns can be either singular or plural.

All, more, most, none, some

You may wonder how some pronouns can be both singular and plural. Review the following examples:

Some of the information is inaccurate.

Some of the figures are inaccurate.

If grammar is a weak area for you, purchase and use a good reference book.

Principle Two: Writing Concisely

In technical writing, clarity and brevity is your goal. Why take 32 words to express what could be stated in 14 or 15? The dictates of effective technical writing suggest that the average length for a sentence is 15-20 words. How do you achieve clarity and conciseness?

One of the best ways is to look for multiword phrases that can be replaced by one or two words. Try replacing the multiword phrases below with a word or two.

A large number of ________________

Prior to that time ________________

In the process of tabulating ________________

As shown in table 3 ________________

Exhibits the ability ________________

Similarly, when you streamline sentences, your readers don't have to wade through extra verbiage. How would you streamline the sentence below?

"To obtain maximum performance from your computer, you should endeavor to follow the maintenance program furnished in the manual accompanying your computer."

Experts have found that there are two ways we lose our readers: using words with which they are unfamiliar and overly long sentences. By replacing wordy phrases with shorter ones and by pruning the deadwood from sentences, you are doing your readers a favor.

NOTE: Answers: many, before, when tabulating, table 3 shows, can

To enhance your computer's performance, follow the manual's maintenance program.

Principle Three: Using the Active Voice

Imperative sentences, or command sentences, are written in the active voice. The active voice is more natural to people when they speak, but technical writers often turn to the passive voice when writing technical documents. One of the main reasons you should use the active voice rather than the passive in technical writing is the active voice more closely resembles the way people remember and process information.

Compare the following sentences:

Staff hours are calculated by the manager on the actual work load.

The manager calculates staff hours on the actual work load.

In the active voice sentence, the subject acts. In the passive voice sentence, something is done to the subject.

Another reason to avoid the passive voice sentence is you run the risk of omitting the doer of the action. Note the absence of the "doer" in the following sentence:

Documented practical examinations will be given for backhoes of the same type with different operating characteristics.

Your reader will probably wonder who will give the practical examinations. If the technical writer had used the active voice, the "doer" would be clear.

Principle Four: Using Positive Statements

Technical writers should word instructions as positive statements. Whenever possible, phrase commands in a positive manner. Compare the following:

Negative: Do not close the valve.

Positive: Leave the valve open.

Telling your readers what NOT to do is a negative statement. It is also abstract rather than concrete. Your readers have to take time to think about what is true (positive) so they can determine what is NOT true (negative).

One exception to this rule is when a negative statement is clearer than a positive one. Keep in mind studies show it is almost 50% harder for your readers to understand the meaning when you use negatives.

Principle Five: Avoiding Long Sentences

Short sentences are easier to understand than long sentences. For this reason, it is best to write your technical documents in short sentences. If you are asking your readers to perform several actions, begin the step with an active verb. This highlights the action itself. Compare the following sentences:

Example of a sentence with multiple steps within the sentence:

For Forte applications, create an empty workspace, populate it with application source code, and compile the workspace.

Example of a sentence with multiple steps set apart:

For Forte applications, perform the following steps:

• Create an empty workspace.
• Populate it with application source code.
• Compile the workspace.

Another tip when separating steps into distinct bullet points is to make sure that the action verbs in each bulleted item are in the same tense. For example, if the first step was worded, "Creating an empty workspace ," then the next bullet would be, "Populating it with application source code ," and the third bullet point would be, "Compiling the workspace ."

Principle Six: Using Standard Punctuation

Your readers expect standard punctuation when they read your documents. Complicated or "creative" punctuation will confuse them. One suggestion is to select syntax that minimizes the need for punctuation. You may wish to divide compound or complex sentences into shorter sentences to avoid excessive or confusing punctuation.

One example of this is deciding where to place your commas, periods, colons, and semicolons when using quotation marks. Commas and periods always go inside the closing quotation mark.

Examples:

We are "struggling young artists," but we hope to become successful.

Most corporations adopt the belief, "the customer is always right."

On the other hand, semicolons and colons are always placed outside the quotation marks.

Examples:

These actors can deliver "box office hits": Tom Cruise, Tom Hanks, Johnny Depp.

Look in the manual under "text messaging"; the directions are very clear.

Many technical writing workshops focus on advanced topics, expecting participants to already be familiar with the basic tenets of good technical writing. While these six principles are a good starting point, you may be surprised to see how often they are ignored within your own organization—and your industry. Challenge yourself to read and analyze other technical documents and ask yourself: What makes some documents a struggle to read while others are easy to comprehend? As you incorporate these and other sound writing techniques, your readers will benefit.