Archive for Technical Writing

Samples

Designing end-user documentation and training

One of the major problems I encounter with technical training and documentation is that it so often focuses on product features rather than real-world tasks users need to do their jobs. My approach is to start with learning objectives and an audience profile and then seeing how the technological feature fits in.

The following two samples (one for training and the other for technical documentation) describe the solutions I employed. They are followed by a new course design I create for a new course at BCIT where I teach.

CKD Patient Registration

With CKD Patient Registration (designed for clinical staff to enter important kidney care information into the clinical software system), the first challenge with training was economising the efforts taken to create and maintain the documentation. I always advocate for a single-source solution that organises information into chunks for re-use. While the ultimate solution is to use a topic-based authoring tool such as Madcap Flare, something similar can be obtained using less feature-rich software.

With the samples below, I started with that big picture of single-sourcing and drilled down to a lesson organised into different clinical scenarios for transfering patients. Although the Adobe Captivate elearning isn’t available to share here, I’ve included similar material (KCC Patient Transfers) that, for the first time, links the software features to real-world clinical procedures.

Selected files:

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):

Course Design Samples

The following samples show a sample course design done for a course at BCIT.

Choosing a Style Guide

If you’re a writer, particular a writer where technical accuracy is important, you need a good set of standards as your reference point. Style guides establish standards and consistency and are especially useful to large organizations where many people are working together on the same project. Below is a sampling of several style guides; some are industry standards used by technical writers while others provide an insight into in-house standards used at differing organizations.

Download any you like:

  • The Chicago Manual of Style – A great resource for technical writers. There’s great information also on laying out documents according to their type.
  • Strunk & White – Elements of Style – This is still a standard even though some of the prescriptive directions seem quaint nowadays (literally).
  • Microsoft Manual of Style – Check how it describes Windows interface naming
  • Apple Style Guide (2009) – Check how it handles units of measure
  • BCIT Graphic Standards 2013 – Even images and graphics need a style guide. This graphics standard guide from BCIT is typical of this genre and of great use to anyone how wants to design a manual to represent BCIT. It includes exact descriptions of branding, logos, colours, type faces, and more.
  • WorkSafeBC Editorial Style Guide – This is a good example of a style guide used in-house by a large organization. Their treatment of how to handle jargon in writing is worth a read.
  • Vancouver Style Guide – This guide, from the University of Queensland (Australia), describes a citation standard known, apparently, by librarians as Vancouver style.
  • Canadian Press Style Guide An Overview – This excerpt from the CP style guide provides good information on how to handle (i.e., capitalize) formal titles.

10 top stories – tooting my own horn

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!

 

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.

Testing Technology: The Key to Top-Quality Fleet Management Solutions

 

WEW-QA_Time-Machine As a pioneer in automated GPS location-based technology at Webtech Wireless we design our own hardware and software solutions. This provides us with the necessary control to build and deliver the solutions our customers rely on. In order to ensure our products are secure, reliable, and robust enough to outlast diverse road conditions and meet industry standards for heavy-duty vehicle applications, the key to our success, (we have delivered hundreds of thousands of Locators that process millions of transactions a day), comes down to one thing—TESTING.

We hire the best network operations and engineers available in the industry and it’s on their shoulders to ensure our GPS fleet tracking solutions keep working around the clock every day of the year. I dropped into our testing area to find out more about why it is that Webtech Wireless is indeed an end-to-end solution for fleet GPS tracking.

Quality Assurance Means Testing, Testing, Testing

Sarkis Teghararian, Manager of Hardware Engineering provided me with an excellent overview of the facility while Kevin Lockwood, Hardware Engineer, continued testing Locators in the background, occasionally adding valuable commentary to my questions.

 

WEW-QA_Kevin-Sarkis

As we entered the work area Sarkis explained, “We develop and test all our products and increasingly we test third-party products as well. Depending on the needs, complexity, and phase of the project, testing is done either in-house or outsourced to other testing labs” Testing equipment is arranged in a series of stations, each dominated by some device I would later learn has a specific testing role to play. Before I could learn more about all these cool testing stations (and about the intriguing command module-like chamber in the corner), I first needed a quick lesson in quality assurance.

A Quality Assurance Primer

Depending on the needs, there are different types of testing. For example, derivative testing verifies only changes to a product, pre-qualification testing ensures a prototype will stand up to its design specifications, and regression testing validates new features including their impact on pre-existing components (i.e., it tests that new features don’t compromise the old ones).

In addition, I needed to know that there are two distinct phases of testing:

  • Development testing to validate new designs
  • Manufacturing testing to validate that manufactured units are built according to specifications

Testing for an End-to-end Solution

When testing gets to the manufacturing QA phase (ensuring manufactured quality) it’s tested differently. With the design already verified, testing becomes more granular, “but” insists Kevin peering up for one of the WT 5130 Locators, “each and every unit is tested”. Because each unit must be tested individually, testing is to a large extent automated. “Some components are manufactured in China”, continues Kevin, “and some locally, so we test to ensure all are manufacturers are building according to specifications.”

A key component of Webtech Wireless’ offerings is end-to-end solutions, but what does that mean for quality assurance? The answer is system testing. Units aren’t just tested by themselves, but also as they relate to a custom-designed solution for a specific client. So, a Locator that’s tested for compliance with manufacturing specifications is also tested with Webtech Wireless software and then again with an EOBR (electronic onboard recorder) such as the MDT 3100 to ensure they work in concert.

Enter the Time Machine

WEW-QA_Enter-the-Time-Machine

Sarkis refers to it wryly as the “Time Machine”, but it’s no joke—on closer inspection, I see that it is in fact branded officially as the GTEM ETS Time Machine. Before my imagination can run too wild, Sarkis brings me back patiently explaining that this machine tests the long-term effects of radiation from GPS and cellular transmissions. During the design phase, for example, a new Locator is placed into the time machine, which tests that its design is solid. The machine is able to speed up the exposure rates and thus reduces both the time it takes to test, and also the cost of testing. Among other criteria, the Locator is tested against its radio frequency rates, how well its circuitry responds, and how well it is able to communicate wirelessly with the base station.

Future Proofing

Quality Assurance is about “continuous improvement”, asserts Sarkis who cites the development of a new audio/acoustic booth to the roster as well as empirical testing to increase the precision of testing. In the future, we also plan to increase the testing of third-party integrations and products. All of this so that we can deliver the incredible reliability that our customers expect of us in a GPS/AVL solution that customers trust to make decisions with every minute of every day.

Webtech Wireless Taking off with Airports

Webtech-Wireless-Taking-off-with-AirportsWith summer winding down and kids going back to school, most people are thinking beyond holidays. At Webtech Wireless, we’re ramping up for a busy season of fleet management trade shows and conventions, and that means we’re spending lots of time in airports getting to and from these events.

Airports tend to embrace new technologies quickly, especially when the technologies can be shown to reduce cost and improve security. Webtech Wireless has airport security perimeter ground vehicle solutions at several major airports in the United States, including John F. Kennedy, LaGuardia, Massport (Boston), and O’Hare International in Chicago. Here’s what we’re doing in Chicago.

Chicago O’Hare International Airport

The City of Chicago’s O’Hare International Airport is owned and operated by the City of Chicago’s Department of Aviation. As a Webtech Wireless customer since 2003, we provide solutions to many of the City’s 2,500 vehicles (including vehicles in its various public works departments). Our airport solution is used to transmit critical location data from designated City of Chicago vehicles every ten seconds alerting the City of runway incursions and security breaches. We also provide automated vehicle location services (AVL) for its snow removal equipment.

As it is not operationally practical to maintain two-way radio communications between every vehicles and airport operations, GPS/AVL technology helps the City track its vehicles. Also, as the speed limit within the airport security perimeter at O’Hare is 30 miles per hour, our vehicle reports help City fleet managers ensure their vehicles operate within the airport’s speed limit.

On the technical side, our AVL solution is ideal for airport operations, because it’s designed for vehicles operating in an 802.11b coverage area; that is, it uses a point-to-multipoint configuration with an omnidirectional antenna located in a coverage area around the access point.

Fly with Webtech Wireless

Webtech Wireless is flying off to several trade shows this autumn. Follow our Events page, which is updated with new events regularly.

September 5 Snow-N-Ohio Workshop Perrysburg, Ohio
September 13 2012 Iowa Snow Roadeo Des Moines, Iowa
September 16 BC Roadbuilders Association Fall Conference Kelowna, BC
September 20 Snow and Ice Symposium Milton, Ontario
September 21 Truxpo Seminar  – Abbotsford Abbotsford, BC
September 23-26 TMW TransForum Orlando, Florida
September 25-27 Association of Municipal EMS Conference (AMEMSO) Ottawa, Ontario

 

My Writing: What’s the most common grammar error? – (July 9 – 23)

It’s been a couple of weeks without an update, but the writing goes on (along with lots of copy editing of others’ works not mentioned here). This gives me an excuse to use a unit of measure almost unknown in North American English: the fortnight, British English for two weeks (fourteen days).

I recently heard that English doesn’t suffer from a lack of a clear second person plural, but in fact from a lack of second person singular. The classic greasy-diner waitress who asks, “Okay, what do yous guys want?” is not inventing a second person plural to distinguish from its identical singular form, but is in fact doubling an already second person plural form. “You” is plural; the singular form is “thou”. So, next time you’re dining alone, an informed waitress could ask you, “What dost thou want?” Or, maybe not.

Below are my corporate blog post for the last two weeks:

What Do Lawyers Cost? is overview of what you need to know before you decide to hire a lawyer to represent your claim. You want one who acts solely in your best interests, advises you to protect your rights, positions your claim to obtain a fair settlement from your perspective, and decides what compensation you deserve for your case.

 

Disabled, “Yes”; Unemployable, “No” describes the Government of Canada’s 2012 Economic Action Plan. By investing an additional $30 million over three years into the Opportunities Fund,  more Canadians with disabilities have the opportunity to become gainfully employed.

 

ICBC and Drunk Drivingdescribes ICBC’s aims in preventing drunk driving, which includes convincing drivers (demographically young men) that making excuses and rationales for why it’s “okay” to have a few before getting behind the wheel is part of the problem of drunk driving itself.

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.