Usability Fun and Games

I convinced myself that applying for a job through the IBM web site was a good use of my time, but I didn’t factor in how much fun it would be.

Like many mega corps, the IBM site asks us to upload our résumés and then goes on to ask us to enter all the same information again manually, field by field. By the end, we’re likely to conclude that any job we should ever get at IBM will net us similar mindless work. But who knows, filling out online applications is my form of Vegas—’cause ya’ never know…

Here’s the kicker. In the section for language competency, I was given a list of languages and a ranking system from which to choose: fluent, intermediate, basic knowledge, and no knowledge. I don’t know what the value is in adding information about a skill in which one has no knowledge. I mean, I could go on and on.

I couldn’t help myself, so I obliged!

No Knowledge required

Three Ways to Improve Your (Technical) Writing Skills

I get asked more frequently about how to make inroads into the field of technical writing and my response generally comes down to three key points:

  1. Get educated: Many technical schools and universities have technical writing programs. They often offer their courses on an iterative basis (i.e., you don’t have to commit to the entire program; you can just take a course or two to try it out). Apart from the training you’ll get, formal training is also a great way to network and immerse yourself in the milieu of technical writing.
  2. Get Informed: Check out the job boards and read the requirements for various jobs in technical writing. If you find the requirements daunting—don’t be discouraged. Many job descriptions are little more than wish lists, but they’ll give you an idea about the kind of skills you’ll need to succeed and the range of industries that need technical writers.
    Tip – rather than searching for “technical writer” over a large date range, I view all posted jobs in, say, the last three days. Positions that require technical writing skills are frequently posted under other names than “technical writer”.
  3. Get involved: Find opportunities to write—don’t wait for a paying job. You may want to volunteer with some non profit or other group as a writer just to get experience. Everyone needs good writing and if you can provide it, you’ll start to acquire samples of work (ensure that any freebie work you do comes with the understanding that you’ll use finished writing as samples of your work).
    I volunteer as a writer for the Vancouver Observer (an online magazine) and it is definitely helpful for keeping my writing skills honed as well as for networking.

Some notable Vancouver job boards:

Testimonial – “well regarded by the students”

Allow me to introduce Jason Hall. He is a fellow instructor with BCIT’s Technical Writing Certification program, teaches on a variety of subjects, and is quite well regarded by the students.

—Steve Bain, Technical Writing Instructor, BCIT

Seminar: What’s the real job of a technical editor?

The Editors’ Association of Canada-BC presents

What’s the real job of a technical editor?

A One-day Seminar

Editors' Association of Canada

If the job of the technical editor is to make complex subjects accessible to normal people, why is it that so many technical documents fail. What is the real job of a technical editor?

Using real-life examples and humour, Jason will demonstrate just how spectacularly technical documents can fail and how you can become an advocate for excellent documentation. This hands-on workshop helps you assess your own skills while exploring what it is technical writers do. By the end of the workshop, you’ll have developed your own toolbox of skills that technical writers need to succeed.

When: Saturday, November 27, 10 AM- 4 PM

Where: SFU Harbour Centre, room TBD
515 W. Hastings St., Vancouver, BC

Instructor: Jason Hall

Cost:

  • Early Bird (on or before Friday, Nov. 12, 2010) Member: $100.00  Non-member: $160.00
  • After Nov 12: Member: $100.00  Non-member: $160.00
  • Note: Registration closes Friday, November 19 at 5 Pm

Register

About Jason Hall

Jason Hall has over 15 years of technical writing and training experience and brings excellence to all his documentation endeavours. He has prepared industry-relevant user manuals and training materials for a great variety of industries from law enforcement to inventory management to health care software products. Past clients include SAP, Best Buy, WorkSafeBC and Health Canada. Jason is comfortable with the full documentation development cycle including interviewing subject matter experts, creating documentation needs analyses, and converting product specs into accessible end-use documentation.

Writing for the Web: Clarity 7/7

Use Standard English

Replace the non-standard English words with their English equivalents. Word constructs like ‘and/or’ and ‘he/she’ are technically not words, so you should avoid them as much as possible. This is a good approach, because it’s easy to rely too much on them even when there is really not logical need. Take for example, “You can call and/or write to request a free estimate”. There’s no real need to say ‘and/or’ in such a situation.

How would you rewrite the following to remove and replace non English words?

  • Our global portfolio (accessed via our web site) invests in U.S. and/or foreign markets (i.e., commodities).

Writing for the Web: Clarity 5/7

Avoid Ambiguous Pronouns

The 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 easily identify the noun that belongs to the pronoun. If more than one noun emerges as a possibility, replace the pronoun with its intended noun.

What’s rolling toward second base?

  • The ball
  • The wall
  • Winfield’s head

Writing for the Web: Clarity 4/7

Avoid Helping Verbs (Might, May, Would, Should, and Could)

Helping verbs, also called auxiliary verbs, are tricky for two reasons: they can have multiple meanings and those meanings are sometimes a matter of interpretation.

EXAMPLE: “When you complete your timesheet, you should be paid.”

If you insert may instead of should, implies possibility or permission.

EXAMPLE: “When you complete your timesheet, you will be paid.”

Writing for the Web: Clarity 6/7

Check Sentences for Misplaced or Dangling Modifiers

Of all grammatical errors, misplaced and dangling modifiers cause the most hilartity. Let’s face it, they’re just plain fun (as long as it’s not you who writes them). In the words of Groucho Marx, “One morning I shot an elephant in my pajamas. How he got into my pajamas I’ll never know.”

  • A misplaced modifier is confusing because, although the modifier may be correct, it’s modifying the wrong word in the sentence.”We almost ate all the turkey” is confusing because it’s not possible to “almost eat” something. The correction is, “We ate almost all the turkey”.
  • A dangling modifier is confusing because the doer of the action is unclear. “After waiting for three hours, the train left the station.” Who did the waiting—you or the train? It’s not clear.

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

Writing for the Web: Clarity 3/7

Simplify the Tense

Unless you’re a time traveller (and therefore comfortable with temporal paradoxes), 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.

English has twelve tenses. Present tense is the only real tense—all the others are factors of our imagination, so don’t make time travellers of your readers by hiking around through your imaginary temporal landscapes.

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

Writing for the Web: Clarity 2/7

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.

Try writing the following sentences in the active voice.

  • The road was crossed by the children.
  • The paint is then allowed to dry for one hour.

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