Testimonial – A most enjoyable class

Thank you again for teaching a most enjoyable class, I feel like I definitely learned numerous useful writing skills. Hopefully I might be in one of your classes in the future.

—Sara, BCIT Technical Writing participant

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.

 

Convect Your Way to Success

Convect Your Way to Success Or What I Learned from Continental Drift

At the turn of the twentieth century, there were two theories bandied about to explain the curious matching of coastlines, most notably the near-perfect spooning of South America into Africa.

One theory put forward was that Earth must have been much smaller in the past and then expanded—like a balloon—forcing the coastlines apart.

The other theory was that the continents simply lost interest in each other and over millennia gradually drifted apart.

Hobby-horse-continents

Originally, the Expanding Earth theory held the dominant sway among those concerned with such phenomena while Continental Drift held little. But over the ensuing decades of research, the two theories reversed their polarity and now Continental Drift has gone mainstream relegating Expanding Earth to a back eddy of angry comic book artists ranting late night on myspace.

I drift. And why not?
It’s good enough for continents; why not me?

The problem with an Expanding Earth is that there’s no known (or plausible) source for that expansion. Where’s all the extra matter coming from and what’s moving it? Whereas Continental Drift has a clear energy source, Expanding Earth has none. You can’t move anything, least of all continents, without energy.

Continental Drift’s energy source emanates from the earth’s core where gravity (the Earth’s and the Sun’s) is heating up the mantle and causing convection to put pressure upon the surface. A common analogy for this process is soup boiling on a stovetop causing its surface scum to move (continents are scum—you heard it here first).

Yes, Continents Drift.
But Whither They Wander, They Care Not.

I knew a man who insisted that medieval maps, with all their childlike inaccuracies, were in their day actually truthful depictions of the world at that time. In his understanding, it was Continental Drift that had rendered the maps inaccurate.

I should have asked if the fanciful marginalia depicting griffins, sea monsters, and galleon-devouring leviathans were also factual, they presumably having mysteriously died off just as the Age of Reason dawned, “Thar be monsters! Oh wait. Never mind, they’re gone now.”

There is an ocean of truth that separates how we perceive things and how they actually go. Imagine, as in the scenario above, if we had gone from Gondwanaland to the present setup in under 500 years. What a bumper-car ballet that would have been—land masses scudding across the seas, their inhabitants waving helplessly from the hilltops as they sailed past. Morocco would say “Farewell”, to Nova Scotia while “Hasta la vista!” would come a final chide from South Africa as Argentina departed bound for pars incognito. “Hey, mind your steppe!”, Nepal and Tibet would sneer in condescending unison at the careless approach of the Indian…ahem…sub-continent.

Other than deep time and incalculable amounts of basalt, what’s the difference between continents and people? If India were—half way along its route into Asia’s underbelly—suddenly to stop mid ocean and say to itself, “Where was I going with this again anyway?” Continents simply drift, but it’s fair to say they never digress.

Continents Drift, but People Digress

As previously discredited, Expanding Earth postulates that there was a smaller Earth, then something (magical) happened, and the Earth became larger. Expanding Earth is pure fantasy yet it does serve to explain how dreamers dream.

I don’t mean visionaries or people who live to see their dreams fulfilled. I mean, unrealistic people or any of us when we’re thinking unrealistically, because let’s face it, it’s in us all to waste a portion of our lives dreaming fruitless nonsense.

We think, in these times, “I’m small and then when something magical happens, I’ll be bigger.” But if we’re to affect real change in our lives, we have to follow the lead set by the continents under our feet. Such change requires constant pressure and patience—the universe is taking care of patience (in spades!)—so it’s our job to take care of pressure.

Continental Drift is sometimes a very personal matter, although in a general sense it can be summed up in the following six-step process:

Step 1:   Set your course in the direction you want to go and then start going there. Talk to people, build your resources, take action, do things, most of all…apply pressure.

Step 2:   Expect nothing (you’re not likely to see any results for a long time). Don’t miss this step—it’s very important.

Step 3:   And don’t digress. Keep applying pressure in the direction you want to go.

Step 4:   Eventually something’s going to give. It will happen like a jolt—like an earthquake. It may even seem like magic (it will certainly seem like magic to others who don’t see all the pressure you’ve been applying). You will have moved incrementally in the direction you want to go.

Step 5:   After the jolt, the pressure will be released for a time. Nothing will start happening again. Don’t worry.

Step 6:   Repeat steps 1 through 5.

That’s it! It’s not magic. Sometimes drifting moves mountains. Hell, it’s good enough for continents, so why not you?

“No man is an island,

entire of itself;

every man is a piece of the continent,

a part of the main.

If a clod be washed away by the sea,

Europe is the less,

as well as if a promontory were.

as well as if a manor of thy friend’s

or of thine own were.

Any man’s death diminishes me,

because I am involved in mankind;

and therefore never send to know for whom the bell tolls;

it tolls for thee.”

—John Donne, 1572–1631

Testimonial – Good jump start

I just wanted to say thanks for being a good teacher. These classes have been great primers for the rest of my education. So thanks for your positive attitude and good jump start.

—Alex, Technical Writing Student, BCIT

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

The Moon and the Leaf Blower

Moon&LeafBlower

Apart from the noise and the self-evident futility of the common leaf blower, what most disturbs me about the whole practice of charging money to fling nature’s bounty into the neighbour’s yard is its name. It lacks a certain…poetry.

In English, we’ve employed clever tricks to give everyday joe-jobs a sense of honour and wonder. These include translation into dessert-sounding Romance languages and obfuscation with marketing bumf (aka, bull).

Take our penchant for French titles. Translating some plain old English thing into French instantly transports it from the mundane suburb where it resides to the court of Louis XIV. Thus, “Kitchen Help” is elevated to “Sous-chef”, “Hairdresser” is blown away by “Coiffeur”, and “Civil Servant” escapes all its grey servitude in the guise of “Attaché”.

We also like to upmarket ordinary jobs by inventing bullshit English job titles. This technique effectively euphamizes their true nature, transforming the lowly “Dishwasher” into a “Ceramic Technician” and the “Garbage Man” (in addition to solving the need for gender neutrality) into the commanding “Waste Aquisition Officer”. This practice circulates so widely it scarcely raises eyebrows anymore, as in the “Marketing Assistant” who now can claim status as “Social Media Guru”.

But “Leaf Blower”…hm. That one stands awkwardly in its field (both the job and the machine)—unadorned and entirely lacking any pretension of upward mobility.

What if we borrowed a little from French—would the title gain some of that gallic allure if we opted for “Coureur de Feuilles”? Has a certain je ne sais quoi, non?

Or taking a more technical tack, we could simply render “Leaf Blower” as “Astro-arborist”, as in “Dammit Jim, I’m just a doctor, not an Astro-arborist!”

Testimonial – Your class has taken my writing up a few notches

Thanks for the class. It has taken my writing up a few notches and has given me confidence that I can move from creative to technical writing.

—Verna, BCIT Technical Writing Student

Testimonial – We have raised the bar

I have very much appreciated working with you and having you on the team. The work you have contributed to does make a significant difference for the product and our business going forward! I believe we have raised the bar at BCLC and hopefully this will encourage others to take their products / businesses to this level.

I have personally learned a lot working with you and have very much appreciated having you around for the past year on our team—your final gift—you have articulated exactly the environment I strive for creating as a professional: “Relaxed Productivity”. I love it! That’s going to be my new mantra.

—Nathan Kulczycki, Product Manager, BCLC

Celebrate National Upspeak Day?

BC Ferries’s busy route plying the waters between Victoria and Vancouver sees lots of tourists, many of whom have no idea about (or care for) the local marine life they’re sailing over.

Perhaps that’s why the crown corporation has seen fit to add a biologist to its retinue of stewards, cashiers, and deckhands—to provide a little eco®–friendly PR about local marine life up top as their powerful propellers churned it up down below.

On a recent trip, the particular onboard biologist on duty delivered her short talk on marine ecology—entirely in up-speak…

She:

“Eelgrass is a flowering plant?”
We:

(Silence)
She:

“It’s found along the coast of BC in sub-tidal areas?
We:

(Silence with a few looking about for the exits)
She:

(Before anyone could decide whether to accept or refute her previous semi assertions),
“Marine animals depend on it for their survival?”

By this point, her up-speak had an urgency that was making everyone uncomfortable. Those who hadn’t already left were now fidgeting with their phones (perhaps hoping the answers could be found there—you never know, debarking might be preceded by an exam). I tried to listen and learn something, but finally got up for coffee and some other less arduous distraction.