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, Technical Writing Student, BCIT
Testimonial – A most enjoyable class
First Words: A Children’s Style Guide
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.
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
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.”
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, Technical Writing Student, BCIT
Testimonial – Nathan Kulczycki, Product Manager, BCLC
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
British Columbia Lottery Corporation
Role: Technical Writer (2016–2017)
Need: In order to “productize” its in-house Lotto! product for external partners (and their clients) in other jurisdictions, Product Development decided its internal technical documents needed to be upgraded.
Solution:
Based on my technical writing skills and my flare for design, I became their document manager. My core responsibilities included engaging with subject matter experts (project managers, developers, engineers, and trainers) to identify audience and scope of documentation (process guides, SDKs, field technician guides, technical specifications, GUI review of user messages and more).
In the end, out of their complex and technical internally sourced materials by multiple contributors, I designed a suite of B2B documents written with a singular voice.
Later, I brought to their attention that their clients had no way to self-serve documents, so I assisted in developing a SharePoint portal with an explanatory matrix to help users understand what documents to use and when.
Tools used:
- Lotto! ticket terminal (used in stores to produce lottery tickets)
- Adobe Creative Suite (Photoshop, Adobe…)
- SharePoint
- Microsoft Office (Word, Excel, PowerPoint…)
Testimonial – All good things must come to an end
When COMM 1008 culminated on August 10, I was reminded of the adage, ‘All good things must come to an end.’ It was a wonderful experience listening to your classes from my last bench. I could proudly say that we have had precious evening hours during COMM1007 and 1008 getting to know the techniques of technical writing and editing. I look forward to working with you in the technical writing world in the near future.
—Shanthini, Technical Writing Student, BCIT
Testimonial – Jon Chapman CEng PMP , Project Manager, BCLC
Yesterday in our working sessions with our inter-provincial customer, they complimented the product document suite. Not only are they starting to realise what a powerful set of documents it is for them, but they also said it presented a really professional image for our product — in fact, they asked if our actual product was as mature as we’re making it look. Great work!
—Jon Chapman CEng PMP , Project Manager, BCLC