Archive for Technical Writing

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

The Future of the Book

With touchscreen technology poised to become a ubiquitous part of our lives, the future of the book is likely to change dramatically as well.

From TED.com – “Software developer Mike Matas demos the first full-length interactive book for the iPad — with clever, swipeable video and graphics and some very cool data visualizations to play with. The book is Our Choice, Al Gore’s sequel to ‘An Inconvenient Truth’.”

Learning Adobe Illustrator

In 2010, I determined that I wanted to improve my Adobe Illustrator skills and so I started creating a mandala a month. Below is the final result.

Copy Editing English for a Globaliz(s)ed Audience

In one of the courses I teach at BCIT (British Columbia Institute of Technology), I received an email from a very keen participant asking how to prepare for the course (Technical Editing and Grammar course – 1008). Inspired by such enthusiasm (this is what makes September great!), I decided to take it further and include  information for anyone interested in improving their core skills as a technical writer.

Get a Quality Style Guide – Consider ordering the Chicago Manual of Style (I have both an online and hard copy version). It’s an excellent investment for anyone interested in high-quality English-language writing.

Learn MS Word – Research the Track Changes feature in MS Word. There are other software programs technical writers need for writing, but MS Word is still the most common. As a technical writer, you’re expected to use Word at an advanced level.

Learn hard copy markup – It may seem archaic, but hard copy markup makes you indispensable when editing and developing large documents).

Learn the Most Common Grammar Errors – In my course, we learn the ten-top grammar errors. Don’t feel you have to know all grammar errors (that’s what a good style guide is for), but your credibility as a writer is increased exponentially if you know the core ones. To find out the ten-top grammar errors, take my course.

Write, write, write! – to get your foot in the door, take every opportunity you can to write and edit even if it means working for free. Ensure you ask low paying (or non paying) clients to let you keep a copy of the before and finished versions, so you can use them to market yourself.