Archive for Technical Writing

First Words: A Children’s Style Guide

First-Words

From “Children’s Games” by Pieter Bruegel the Elder, 1560

I was musing today about the peculiarly magical vocabulary of children, and then started recalling some special words from my childhood. I love these words because they represent a lost innocence of language—like a dead language we all experienced first hand but have hidden away for safe-keeping.

Such words are not easy to remember perhaps because most were trampled (in some cases painfully) by sensible adult words. Somewhere along the line, I learnt not to say “lightning bug” anymore because the correct name is “firefly”; same with “shooting star”, it’s “meteor”. But there are also silly words that no adult could have talked us out of, like “pee-pee”, “bumblebee”, “piggyback” and “choo-choo train”, which are special simply because they’re fun to say.

And then there are those golden spoonerisms, mistaken words that sunder the language with unimagined new sounds. Words like “bisghetti” (“spaghetti”), “bolleyvall” (“volleyball”), “varine” (mine for “ravine”), and my younger sister’s tour de force “Principal Lion” (for “Prince Edward Island”).

I tried to find some sort of style guide on children’s words but came up empty handed. A brief search of the Internet revealed itself tiresome and cynical offering none of the magic but only grey pedagogical resources on correcting children’s speech or exploitive photos of salacious spelling errors found in children’s art. “Well son, your innocence would have been lost altogether had we not posted it to the Internet.”

Do you have special words hidden away since childhood? If so, write me and let me know. I would like to gather them into a style guide of children’s words.

Please include the following:

  • The word and its meaning (or your younger self’s interpretation)
  • Your name and city of origin (if submitting on behalf of someone else, please include that person’s name and your relationship).
  • If possible, the known age of the person when this word came into being (an approximate is fine).

View a sample of First Words – A Children’s Style Guide taken from what’s been collected so far.

Lost in Translation: How Poor-Quality Documentation Costs You Money

Lost in Translation: How Poor-Quality Documentation Costs You Money

A number of years ago, the software company where I worked was struggling to keep its translation costs down. One day I drew the connection between our ongoing need for consistent writing and the costs of translation. For example, we would use “record” and “transaction” to mean the same thing (in truth, it described a process of data records becoming financial transactions, but our readers didn’t understand that until they became experts themselves) and this confused not only our English-speaking readers but it created headaches for our translators. Translators typically charge by the word but they also keep lists of common terminology to save them time.

When preparing documents for translation, consider some of these common errors to avoid.

Images may need to be translated

Not only does the text that appears in images need to be translated, but the images themselves may not translate well to a particular region or culture. Translation is after all a form of localization, so check your images carefully and alert your translators to check them too.

When I was preparing a document on snow plows for translation, not only did the vehicle we’d chosen have to be checked for authenticity to the region (do they have snow plows like this there?) but we also had to decide whether to Photoshop a translated version of “snow removal” printed on the vehicle or just erase it (we did erase it in the end).

Corporate branded words and phrases may OR MAY NOT need translation

There are lots of funny rules around how branded words and phrases should be handled when a document is translated. For example, I worked at a company that had trademarked the phrase “telematics for the planet”. But it was only ever trademarked in English, so we had to instruct our translators to let this stand even when used in the flow of a sentence.

Lorsqu’on utilise nos produits, ne soy pas oubliant « Telematics for the Planet™ »…

Translation also needs to be localised

A good translator is on the alert for terminology that is appropriate for the audience. A good translator will also alert you to figures of speech, metaphors, and clichés that don’t translate at all. Keep your technical documents free of such writing and you’ll save money on back-and-forth communications.

What’s worse than the over reliance of metaphors in writing? Why, mixed metaphors of course. Just imagine translating this baby into Spanish, or German, or Russian.

Inflation is a very difficult genie to put back into a bottle so you’re not going to be able to stop on a dime.

Units of measure may need more than just language translation

Units of Measure are also a form of localisation that are frequently overlooked. While our English-language documentation was destined for the American market, we always preferred Units of Measure to be listed in American measures (with metric in parentheses). This detail eluded us when we sent the same documents for translation into French (bound for a Quebec audience) and it came back with all the American measures carefully translated into French even while Quebec (and indeed all of Canada) uses metric measures.

 

Singing The Single-Sourcing Blues

Photo credit: Creative Commons
The following somewhat (but not entirely) fictionalised story commemorates a failed attempt to impart upon a decision-maker the benefits of single-sourcing technical content. 


Installation High

A 30-day free software trial of Madcap’s Flare software seemed like the way to go to get us out of the tired rut of our end-user technical documentation. This product’s offerings of single-sourcing capabilities included content tagging for advanced cross-referencing, sophisticated importing and exporting, team collaboration (with multiple levels of access for reviewers), and most of all, topic-based structuring.

Photo credit: MadCap Software, Inc.

When I met with the decision-making manager, his first question was why I needed 30 days. “Well”, I said as diplomatically as I could, “I don’t expect to be assessing the software 40 hours per week for 30 days. That’s just Madcap’s trial period.”

But that was just his warm-up because he seemed to have other plans in mind. “Before we start looking at new software”, he said, “perhaps we need to step back and assess what our users need.” Normally this would seem like a reasonable suggestion, but to date no interest had yet been shown about user needs, so why now? I suspected a delaying tactic.

Big Data for Small Minds

The manager offered to run some analytics on traffic for our Webhelp and maybe even send out a survey to all users so as to solicit their feedback on the documentation. The manager seemed confident that something would come of engaging our users, although I already knew that we had very little data on usage and that it would be very easy to draw whatever conclusions we wished from analytics. If this is the requirement needed to install a 30-day free trial of software, I thought, why bother?

“Have you thought of using WordPress”, the manager queried. I made a point of not letting my emotions show, but some part of the cheery recommendations I was planning died in that moment. “No”, I said but added quickly, “How would you implement a single-sourcing solution with WordPress?” The manager waned in his enthusiasm a little, so I took the opportunity to explain the problem/solution further.

“We have a large array of documents (user guides, training handouts, change management documents, release notes, and on and on) all of which are maintained in a way that creates great inaccuracies and much wasted time keeping track of revisions and duplicates.”

Magic Bullet Point

By mentioning the problem with duplicates, I thought I’d laid down a trump card of sorts, but the manager took it to mean that I was prey to some form of technical writer magical thinking.

“There is no software that’s going to prevent duplicates”, he said, “People, no matter how great the software, can still create duplicates.”

I had to pause at this. I wasn’t proposing a magic bullet. I knew full well that software has limitations. I needed an example to put him squarely in the seat of what the present system is like and why it isn’t working.

“When you drive down the road, there’s nothing preventing you from swerving your car into oncoming traffic”, I went on, “You can do it, but what’s preventing you is your agreement (coupled with myriad laws and cultural taboos) to play within the rules.”

“Of course, people can still create duplicates, but what we need is a set of tools that point us toward good practices rather than the current system (Word documents stored on people’s C drives) that get copied, and copied, and pasted, and then re-copied across the system in a way that’s prone to error. Then, if there’s a change to be made, who can find all the documents affected and change them?”

Enter Steve Jobs

The manager conceded my point, but then he went off in another direction to question the need for documentation—AT ALL!

“Do you have an iPhone”, he asked.

“Yes”, I replied.

“Did it come with a manual?”

“Well, yes it did”, I confirmed suspecting now where his questions were leading.

“Have you read it?” This was his turn to sound triumphal.

“No, I haven’t”, I said.

“You see!”, he erupted, “You have an iPhone and it has a user manual, but you’ve never read it!” He seemed almost delirious at this portrayal of software so intuitive it didn’t even need a user manual. Clearly, Apple in its magnanimity was providing user guides only as a form of self-effacing humility.

I thought it wise to choose my words carefully, so I paused. And then I said, “It’s true. Since I came to your software company, I have worked on the assumption that we all agree that there is a need for software documentation.”

Then I launched my final salvo.

“When your software is designed to Steve Jobs’s and Apple’s standards—that is, it’s so intuitive no user guide is needed­—I’d welcome the idea of dropping documentation. But I’m working with the system as it is now.”

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.