Focus on Technical Writing

10 top stories – tooting my own horn

22 August, 2014 / Jason Hall / No comments

Award-Winning

Over the last five years, I’ve written so many stories, blogs, and articles that it’s easy to lose track of what they are and what made them work.

To come up with a short list, I’ve chosen ten top stories and assigned “award categories”:

Best headline – This concert review might have gone unnoticed had I not tied one of the pieces performed with issues critical to The Vancouver Observer’s news coverage. The result: Erato Music got much more attention from readers who might not otherwise have taken an interest in chamber music.

“Oilblood” re-imagines Harper with Baroque vengeance

Best use of images (supplied) – I worked with Bicycle Opera and their photographer to find really compelling photos to help tell this interesting and quirky story. In the end, I also pirated several photos from their Facebook page

Bicycle Opera wheels into rural Ontario

Best use of images (I took) – This was a really interesting article to write. It was part music story, research project, and travel story and perhaps owing to the fact that I was a participant to these workshops in California, my photography skills came through.

The Balkan Music and Dance Workshops: re-thinking dissonance

Best niche story – There’s no niche for this story really, because it’s so weird an quirky. Still, there’s a real person who made his own drum kit that could be transported by bicycle.

Musical instrument makers on bikes

Best interview –  Also, on the theme of musical instrument makers, this story describes in great detail two Vancouver-based musical instrument makers. I visited their workshops and photographed them at work.

Discovering Vancouver’s hidden music makers

Most detailed historical travel story – I like this story because it shows one of the most saturated travel destinations, Paris, from the perspective of a lone cyclist not afraid to go anywhere to dig up some good history.

Unforgettable bicycle trips around Paris: Notre Dame, Château de Vincennes, Arc de Triomphe

From my three-and-a-half years at Webtech Wireless, a few outstanding stories emerged:

Best corporate technology story –  I attended a trucking trade show in Orlando and attended a talk about data – yawn. But wait, then I wove it into a colourful story drawing a thread of continuing from Sumo wrestlers, Arkansas Governor Mike Huckabee, and Québec performance artist, Jean Francois–all who had something to say about perspective.

Drawing Intelligence from Data

Best corporate human story – I interviewed Webtech Wireless firmware engineer, Alireza Nematollahi, and wrote about his success as a national kayak champion and drew a connection to his testing work at Webtech. When I criticize formulaic blog writing, I see this as an example of what corporate blogs could be. 

Testing the Limits

Best corporate hay-making story – Here, I found a connection between the temperature monitors Webtech Wireless makes for food transportation and world hunger. The statistics for food wastage in transport are huge, so it wasn’t an unreasonable stretch–certainly one I was happy to make.

Cargo Temperature Monitoring Helps Reduce Hunger

Best corporate culture/technology tie-in story – I decided to write our weekly blog as a travel story and sing the praises of Ottawa’s winter celebrations (and its fabled Rideau Canal skating rink), while slipping in the expected corporate blog about how the City of Ottawa uses Webtech Wireless technology to ensures its roads are kept ice free.

Winter Fleets—Let’s Celebrate!

 

Trucking software user guide

13 December, 2013 / Jason Hall / No comments 
Type: User Guide
Objective: Show how to use in-cab software
Purpose: Reduce calls to Tech Support
Audience: Trucking drivers and managers

Webtech Driver Center User Guide

Audience profiling is an important part of training and documentation. For this next sample, we already knew that our audience (truck drivers and dispatchers) was highly visual and independent. I recommended building a guide that was down-to-earth, and I tied each procedure to a task in the order that the user might encounter it during a typical work day. It might seem obvious, but this approach replaced a rather stuffy technical writer style of documenting every feature whether or not the user was likely to use it (we stuck to documenting 80% and left the remaining 20% to Technical Support to address should the user need arise).

Selected chapters from the guide (I designed this document in InDesign using some of its responsive design technology to allow readers easy reader whether on a desktop or mobile device):

Testing the Limits

10 October, 2013 / Jason Hall / No comments 
Type: Blog post 
Objective: Highlight employee successes 
Purpose: Build trust in company offerings
Audience: Subscribers to GPS/telematics newsletter

 

Testing the Limits

Testing-the-Limits

When you master a skill, it can appear simple, almost effortless—but that’s just an illusion. Mastery takes hard work and dedication. This week, Webtech Wireless salutes our very own firmware engineer, Alireza Nematollahi (Ali), who’s been pulling in the gold as national kayaking champion while working to ensure Webtech Wireless hardware products are put through tests of their own.

Ali Tests the Limits

Ali works on hardware engineering projects at Webtech Wireless, either involved with new deployments or redesigning existing products and processes for increased efficiency. “Currently, I’m redesigning the automated testing hardware to improve how we test our locators”, he says and then explains that locators were tested manually, but “due to complexity of the locators, they are not human testable in a timely manner. By automating the testing, it will be possible to test up to 24 locators simultaneously.”

My impression of a slow hands-on testing process replaced by a faceless machine is dashed by Ali’s description of the rigorous test procedures in automated testing. Automation is more than just hurrying up (although that certainly is one aim). Automated testing improves how Quality Assurance analyzes the test data through improved reporting, and by analyzing the reports, they can continuously improve testing.

“I Will Be Fast!”

Ali has won a dozen or so medals over the years competing as a flatwater kayaker, and he credits his success in part to having “the best coach ever”.  Six days a week, you can find Ali training, either on his own in the gym or on the water with Kamini Jain, a two-time Olympian. Her motto, “I will be fast!”, must be what inspires Ali to say things such as, “You can do whatever you want”, and “I can be successful at my job and I can be successful at my sport”.

Overcoming Adversity

Although he’s not a professional, Ali has competed and won against the best in the field. He won the men’s gold medal at the national finals in Regina and won gold in Seattle’s Ted Houk Regatta K4, but is still content to have placed seventh this year in Montreal. “Does it seem like a failure to only place seventh after winning gold”, I asked, but Ali’s answer is a case in point of what a winning attitude is all about. “It’s not a failure. Seventh is very good, and failure is what motivates me to do better”.

On adversity he says, “I don’t let myself get caught up in comparison with others or my earlier successes. Comparison will tear me apart from the inside. I’m always thinking about the next regatta and the next year.” Then he adds, “Failure motivates you to do better.”

It’s pretty clear from talking to Ali that his training has prepared him for all the tests that life can offer, both at work and on the water. Congratulations for being an inspiration.

Navigating the Digital Oil Field

18 February, 2013 / Jason Hall / No comments 
Type: Blog post
Objective: Describe "digital oil field" technology
Purpose: Improving budgeting and forecasting
Audience: Decision-makers of OnG trucking fleets

Navigating the Digital Oil Field

With supplies of easy oil running low, oil and gas companies are increasingly turning to technology to help them get the most out of the extraction process. Around the world, energy companies are advancing the limits of digital oil field technology, a recently coined term to describe this emerging segment of the industry.

The “digital oil field” describes computer technology deployed to automate oil and gas extraction, and it has been given a lot of attention for good reason. Digital oil field technology aids a wide array of Oil & Gas activities from exploration, surveying, development, and well completion to data integration of seismic imaging, drilling, process completion, reservoir modeling, and production optimization. This information is then fed to data centers in real-time, allowing experts in the industry to optimize production and minimize downtimes. According to Booz & Company, a leading global management consulting firm, “digital oil field technologies could increase the net present value of oil and gas assets by 25%.” The global digital oil field market is estimated to be worth $18.7 billion and is forecast to reach $33.3 billion by 2022.

While not generally included within the description of digital oil field technologies, telematics operates on the same principle—making better business decisions because you have the data to show where your vehicles are and what your drivers are doing in real-time. For example, with an automated tool for tracking vehicle whereabouts, IFTA fuel-tax information is gathered automatically and therefore accurately, and these accuracies save you substantial revenue from higher taxes. Also, you don’t miss out on additional savings if you operate in jurisdictions in which offer off-road usage earns fuel-tax credits.

As data accumulates over time, your ability to budget and forecast improves exponentially because you have accurate and historical data at your fingertips.

 

Possessive or Plural?

24 April, 2012 / Jason Hall / No comments

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…

Five Super Fantastic Tips to Improve Your Writing

19 March, 2012 / Jason Hall / No comments

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

29 October, 2011 / Jason Hall / No comments

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

25 October, 2011 / Jason Hall / No comments

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

23 October, 2011 / Jason Hall / No comments

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?

22 October, 2011 / Jason Hall / No comments

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.

« Older Entries   Recent Entries »