Archive for Technical Writing

Possessive or Plural?

I’m building a list of real-life grammar error examples, based on my writing, researching, and reading. These examples will all make titallating class materials at BCIT or when I publish my own version of Strunk & White. The examples below focus on confusion about pluralization.

ICBC

As an insurer and issuer of driver licences, we make decisions which can have a significant impact on peoples’ lives.

Problem: People is already plural, so the apostrophe is misplaced. Also, the sentence should use that and not which as it’s restrictive. In editing, the lack of a comma is a giveaway that the writer was uncertain anyway—using which always requires a comma.

Correction:

As an insurer and issuer of driver licences, we make decisions that can have a significant impact on people’s lives.

Construction Company

ABC Crane Service is an Oklahoma based crane rental company that provides crane service nationwide. Their fleet of cranes range from 80 to 660 tons and have been used in projects to solve challenges such as…

Problem: In the second sentence, the subject is fleet, which is a collective noun (therefore treated as singular). The confusion arises from the words cranes and tons (clearly plural) closer to the verb have, but the collective should prevail so it should be has. Other copy errors are indicated, (and corrected), in underscore.

Correction:

ABC Crane Service is an Oklahoma-based crane rental company, which provides crane service nationwide. Its fleet of cranes ranges in size from 80 to 660 tons and has been used in projects to solve challenges such as…

How Much Graphic’s Experience Do You Need?

As a freelance writer, how much graphic experience do you need?

Writers often find themselves involved in the visual components of their writing. This can range from making aesthetic choices for a document to sub contracting a graphic designer to taking a DYI approach and creating graphics themselves.

These days, things are a lot more visual as everything moves online where people tend to even read visually—scanning, foraging, and generally jumping around compared with more traditional linear reading styles.

I just edited a blog post for Webtech Wireless, one of my main clients, and apart from having to revise the text on an image, I designed to improve the overall look and feel of the image. So, not really a functional improve, just an aesthetic call to improve the overall look and feel of a very technical article.

Original

I didn’t have the source for this image—it was just pasted as an Excel® chart in Word®. I find that most graphics created in Microsoft programs look really clunky and, well let’s just face it, nerdy.

Odometer original

Original Excel graphic

Revised

To revise the original, I started from scratch and redrew the content in Adobe Illustrator. I didn’t intend to go quite this far, but one thing led to another and pretty soon I’d built up these dreamy layers of gradients, Gaussian blurs, reflections, and transparencies. I think I’d go for some Jell-O salad now.

Odometer revised

Revised graphic in Adobe Illustrator

In the end, a lot of technical material was rendered a little more, er, palatable with an eye-popping image. Read the article…

Five Super Fantastic Tips to Improve Your Writing

When I’m editing (either corporate technical and marketing materials or student papers at BCIT), I pay particular attention to sentence construction. Technical and business writing is prone to awkward sentence construction, because the material is so complex. And marketing writing only compounds the problem, because the writer feels compelled to decorate the writing with as many superlatives as possible.

Here are five tips I use to keep my writing clear:

1. Avoid nominalization. Most people are familiar with it even if they don’t know what it’s called. In nominalized writing, the writer turns verbs into nouns. It’s most common in bureaucratic writing, and I believe, originates from a writer’s attempt to gain ground on the target audience—it talks down to its readers.

Here’s an example:

Improve driver safety by notification of Emergency through panic button depression.

You can see that nominalization also results in a lot of passive voice. By returning the nominalized verbs into true verbs, your sentence instantly has more life:

To improve driver safety, notify Emergency by pressing the panic button.

2. Keep the subject and its corresponding verb as close to each other as possible.
Here’s an example:

Before:
“This concept demonstrates how simple data related to, for example, salt dispensed on the public highways during the winter months when combined and processed with external data like geo-spatial, traffic fatality, and weather data can be turned into useful information.”

After:
“This concept demonstrates how simple data can be turned into useful information (for example, data from salt dispensed on the public highways during the winter months becomes useful information when combined and processed with external data such as geo-spatial, traffic fatality, and weather data).”

3. Move parenthetic content away from the core of the sentence. In the example above, I’ve moved the parenthetic material away from the structural core of the sentence, but mirrored the point to reinforce the meaning. Parenthetic content is not always contained in parentheses (brackets). You can also use commas and even em dashes to indicate a parenthetic idea. I distinguish each as follows:

  • Parentheses – an idea entirely outside the structural core of the sentence; a lesser point.
  • Comma – a subordinate idea, but closely related to the core of the sentence (i.e., the sentence would be lessened without it).
  • Em dash – a non related point that has a slightly exclamatory quality to it. It’s unrelated to the core meaning, but it’s an important aside—I use them a lot in web writing!

4. Check your logic. The most common logic error in grammar has a name: It’s called the dangling modifier. It occurs in sentences in which the doer is unclear (either because the sentence carries two or more doers or it’s omitted). It’s often the source of humour, as in the famous quote of Groucho Marx, “Last night, I shot an elephant in my pajamas. How the elephant got into my pajamas, I’ll never know”.

Here’s an example taken from technical writing:

“The currently open table appears in the top-left corner of the window.”

“Open” in this case is not a verb; it’s an adjective. The intransitive verb “appears” is doing whatever action it can. “Currently” is a misplaced modifier. It should read, “The open table currently appears in the top-left corner of the window.”

5. Limit your use of adjectives and other superlatives. I call this “super fantastic writing”, because it’s used when “fantastic writing” just isn’t good enough. I recently edited a document that made the claim “…saving you more than millions of dollars in lost revenues”. As in point four above (Check your logic), it just doesn’t make any sense. Without an exact number, you can’t add a superlative (“more than”). As an editor, it’s sometimes difficult to persuade writers to release their white-knuckled hold on such writing—but it must be done. Decorating your writing with lots of adjectives, superlatives, and other do-dads doesn’t make it better or more persuasive.

Grammar tip – Misplaced and Dangling Modifiers

Check Sentences for Misplaced or Dangling Modifiers

Let’s face it, misplaced and dangling modifiers are just plain fun (as long as it’s not you who writes them). A misplaced modifier usually just doesn’t make sense, because they appear to modify the wrong thing.

After our French lessons, we could understand the French spoken by our visitors from Québec easily. It’s misplaced because it sounds like the visitors spoke easily, when it’s our “understanding” that should be modified. “…we could easily understand…”

A dangling modifier often renders the sentence hilarious. The most famous example of a dangling modifier is by Groucho Marx:

One morning I shot an elephant in my pajamas.
How he got into my pajamas I’ll never know.

There are web sites exclusively devoted to documenting them.

Here’s another example: “It wasn’t long before the two got engaged, lived in several Canadian cities, pursued their separate career paths and explored their new surroundings while weighing the pros and cons of each.”

What are they weighing the pros and cons of?

  • Their surroundings
  • Their separate career paths
  • Several Canadian cities
  • Their engagement
  • All of the above

Avoid Ambiguous Pronouns

Avoid Ambiguous Pronouns

Ambiguous PronounThe best way to avoid this kind of confusion (what kind of confusion? The confusion that results from ambiguous pronouns), is to read your copy carefully checking that you can  identify the noun that belongs to the pronoun.

If more than one noun emerges as a possibility, replace the pronoun with its intended noun.

“There’s a high fly ball! Winfield goes back. His head hits the wall. It’s rolling toward second base.”

What’s rolling toward second base?

  • The ball
  • The wall
  • Winfield’s head

 

Simplify Tense

Simplify Tense

Unless you’re a time traveller (and therefore familiar with temporal paradoxes), you’ll be confused by sentences where the writer did not follow a logical progression in time (that skipped writing course at university would have helped now) and now covers too much temporal real estate in a single sentence—don’t you start doing this!

English has twelve tenses. Present tense is the only real tense—all the others are factors of our imagination. The best rule of thumb is to stick to the present tense as much as possible and make occasional forays to other tenses as needed. Don’t make time travellers of your readers by hiking them hither and yon through your temporal landscapes.

EXAMPLE: “Madonna removed her wedding ring before she appeared last week sparking rumours that her marriage is on the rocks.”

What’s a Technical Writer Worth in Vancouver?

My students frequently ask me about salary ranges for technical writers and, occasionally are confronted with their expected salary range on a first job interview. Based on Stats Canada information, you can add a job title, city, and province and find out what the salary range is. Here are the latest statistics on what salaries technical writers get in Vancouver:


Try it yourself.

Use Active Voice

Use Active Voice

Tricky Dick

The phrase, “Mistakes were made” is attributed to US President, Richard Nixon, to acknowledge that the Watergate situation was mishandled. He could have spoken in active voice and said, “Mistakes were made by me” or better still, “I made mistakes”, but he evaded direct admission of responsibility and thereby went down to history as Tricky Dick.

There are three times when it’s appropriate to write in the passive voice:

  • When the doer is unknown. “My bass clarinet was removed.”
  • When the doer is unimportant. “The lab rats were given a placebo.”
  • To protect the doer from embarrassment. “You were overcharged for your purchase.”

TIP: In technical writing, you can distinguish between general concepts and action-oriented procedures by writing the former in passive voice and the latter in active.

Using active voice in web writing adds interest and action to your writing. Good sentences begin with a clearly stated subject (the doer) and a strong verb (action). While it is a commonly used verb, “to be” is passive as it describes a state of being rather than doing. So the more you use “to be”, the more passive sounding your writing will be. Also, some verbs are weaker than others. The verb “to understand” is weaker, because it is harder to quantify and tends to get lumped with another verb that’s doing the real work.

EXAMPLE: To understand how to run for President of the United States, you must have friends in high places.

 

Use Concrete Specific Words

Use Concrete Specific Words

StuffnJunkUsing concrete specific words won’t necessarily make your writing shorter, but it will make it more interesting to read.

Avoid:

  • Several – how many?
  • Numerous – What number?
  • Various – Which?
  • Very – use your imagination!

And of course:

  • Stuff
  • Junk
  • Whatever!

 

Redundancy—A serious and critical crime since 1066

Here’s a little tip from my technical editing and grammar class about why there’s so much accepted redundancy in English:

“It all goes back to that fateful Battle in Hastings in 1066. After the Anglo-Saxons lost, Norman rule was established in England and with it, a second language. In order to rule the country (and be understood), court officials, lawmakers, and judges had to repeat themselves in both official languages (sound familiar?). Commoners, anxious to put on airs and sound official, incorporated these redundancies into everyday language, bringing about some of the phrases we have today:

  • Null (Anglo) and Void (Norman)
  • Just (Anglo) and Proper (Norman)

This writing habit is now so widespread that writers often think they need to use the and/or construct to accommodate both words, when the best solution is to simply remove the offending redundant word or phrase.”