Focus on Technical Writing

Student Style Guide

In my technical writing classes, I often threaten to develop a style guide for that class alone. This would head off students before the blundered into common grammar and stylistic errors. So here it is.

1007 Technical Writing Style Course – Style Guide

 

5 Questions Every Technical Writer Needs to Ask

One of the best skills a technical writer can bring to a company is the ability to ask good questions. When a technical writer shows up at your firm, he should be inquisitive and eager to learn about your content. Starting with the same kit of questions a journalist uses (what, who, why, where, when, how) the technical writer works with subject matter experts to ferret out the information the end user needs.

1. What is it?

Content…

Despite claims to the contrary, not knowing the particulars about a thing can put a technical writer at a distinct advantage. Why? It’s about empathy—about 75% of the time, technical writers are writing for people who share their initial ignorance, so they ask the best questions.

Subject matter experts, by contrast, may suffer knowledge blindness, a form of ennui brought on by over-exposure to the content. Experts have been so exposed to the difficulties of the subject matter, they can hardly remember how hard it was for them to learn it. As a result, assumptions are made, steps are skipped, and conclusions are drawn that seem premature to the reader.

A good technical writer exposes these oversights and writes with the fresh perspective of the reader who is new to the content.

Questions to ask:

  • What is it?
  • What is it used for?
  • What problem does it solve?

2. Who is it for?

Know Your Audience

Technical documents fail not so much because of poor content but because of poor audience assessment. As you can imagine, a software guide that patiently explains what a computer is to an audience of programmers is going to miss the mark—by a long shot! It’s about finding the Goldilocks zone of information—not too basic, not too complex, just right.

I took a PHP programming course in which the instructor got up one morning and launched into 45-minute lesson on how to use “regex”. I couldn’t follow him at all until my thirst for context finally overcame my patience and I blurted out “Where would you use regex?” To which he replied, “Everywhere?” That was clearly no help to me, so I opted for the reductio ad absurdum argument and said “Like on salad?”

This was likely the instructor’s first glimmer that perhaps I was in the wrong class, and this also coincided with him assuming a more condescending tone with me until the end of the term. He was otherwise a good instructor but made the blunder of forgetting that his audience was more novice (in my case, infinitely more) than he.

Armed with a good working knowledge of the audience for technical content, the writer can provide that needed context. Sometimes, it’s good to risk stating the obvious (that is, provide context even when it’s not necessary) as it provides reassurance or confirmation to all readers.

Part and parcel of knowing your audience is making informed choices about what sort of writing style you should use. If your audience is less educated, for example, prefer a simple direct writing style; whereas, if your audience comes from an academic environment, write in a more formal manner.

Some governmental organizations can tolerate a large amount of passive voice and nominalization (turning verbs into nouns), which other readers would find confusing or even condescending. Which brings me to tone (the other side of style). Tone is your attitude to the reader (or the subject matter). Whether collegial or more reserved, the tone for a document is developed from asking the right sorts of questions about the audience.

Questions to ask:

  • Who is the primary audience for this document?
  • Are there any secondary audiences?
  • What is education level of your audience?

3. Why does your audience need to know?

Purpose

Where context allows a reader to know the relevance of the content to something already known, purpose allows the reader to know what will be possible as a result of learning this new information.

Going in, very often, the reader has expectations of the document or the subject matter. The reader may already know things about the content or even have prejudices about it. If the writer can anticipate and address these expectations up front, the reader’s job becomes much easier.

Knowing this information may also help the writer tailor what might motivate the reader as well as address any resistance to the subject matter. For example, an in-house technical manual for a workplace automation tool may benefit with a disclaimer that this new innovation is not a prelude to the unemployment line for its readers.

Questions to ask:

  • Why should your readers care to know this information?
  • What expectations do the readers have for this document?
  • As a result of reading your document what will readers be able to do?

4. When do they need to know?

When…

Technical content sometimes has a shelf life that goes beyond ensuring it’s up to date. Sometimes, the information is only relevant to the reader at certain point and then not again. Once when I was working on a set of technical specifications, I found myself in a room with two subject matter expects both arguing about the specifications for the product. How could they be arguing? Aren’t specifications objective?

Once the air cleared, I realized it was not a matter of what we needed to say but where the document was positioned in the Sales funnel (a Marketing term). We were at the beginning, so the prospective buyer only needed to know if our product complied with their equipment standards. Later on (and further down the Sales funnel), the reader would need a different set of specifications that explained in more detail the requirements for installation.

I always provide connecting introductions to sections so that the reader knows if a particular section applies (or not). If a section is dependent on what came before, I mention that. Remember, readers don’t necessarily read technical documents in a linear fashion so it’s helpful to recap with connecting text. Also, readers appreciate knowing if a section doesn’t apply so they can skip it and move on.

Questions to ask:

  • At what part in the process/workflow does this apply?
  • What conditions apply?
  • What exceptions occur?

5. What’s the Structure?

Organization

Technical documents are not like novels—nobody curls up by the fire with their lapdog and a snifter of brandy to read their favourite technical manual cover to cover. No. Technical documents are only read when there’s a need. As a result, they’re highly structured to allow the reader to jump about as needed.

Creating the structure for a document is called outlining. The outlining stage of writing ensures the document is laid out in a logical and functional way. An outline usually appears as a document skeleton—just a structure, no details. Once approved, the writer fills in the skeleton with paragraph text. Think of a table of contents that precedes a nonfiction book: Major headings of equal value interspersed with sub headings containing subordinate content.

There’s a design element to structure too. Although readers tend to jump and skip around until they find the specific piece of information they need, technical documents are still written in a narrative (or chronological), so good structure (reinforced with heading styles) leads the reader’s eyes to your intended point of focus.

Questions to ask:

  • What’s the logical flow of the information?
  • What are the major components?
  • Where do sub components fit?

Do you have any questions about your documentation needs? Let’s talk.

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.

Grammar NAZIs! Meet your Nuremberg Trial

Or…When good grammar just isn’t good enough…

Vancouver’s suburban Lougheed Highway wends its way through Burnaby with predictable consistency. At each Skytrain station paralleling the route follows a rhythmic punctuation of corporate conformity — a London Drugs, a Starbucks, a Buy-Low Foods, a capping glass condo tower. Then repeat to the horizon line. Monotony enough to put envy into the heart of any Cold War-era urban planner. So much for Capitalist diversity.

How gratifying to know then that there are a few cells of non conformity hiding within the corporate state. Take for example, the copy editor. While much of the literate world has long since parsed out the difference between “its” and “it’s”, how refreshing to come upon a non-conformist writer who dares to shake up the rules of grammar a bit. Otherwise, explain these gems.

With its jazzy use of “it’s”, I find this subtitle scintillating. It jumps out like a tangy note of peppercorn in an otherwise grey merlot. “It’s top business sectors” or more accurately “It is top business sectors” connotes authority in a way the correct form just can’t.

Don’t be fooled — the clever writer of this next one knows how to get eyeballs on paper.

Amphibious

Compared with the worn-out tricks of social media gurus and their endless listicles (“OMG – The 7 Things you need to know about nose hairs that will completely change your life forever!”), I’ll choose the well-placed malapropism every time!

There are corporate disruptors; then there are the outright anarchists. The latter I believe to be behind this next masterpiece of subject/pronoun mixology.

Subject/verb agreement magnum opus

Subject/verb agreement magnum opus

Putting aside the grey imagery of office furniture representing not a company and most certainly not people, it would be so simple to just change “company” to “companies” and put an end to this vertiginous dance between the pronoun (“them”) and its potential suitors (the two nouns in the sentence). But isn’t “company” a “them”, which has people in them? Yeah I s’pose, but it’s a collective noun so it should be singular…but wait, it’s people we’re talking about…them is people. Inside people? You see. That’s why I prefer the roller coaster whiplash Magna Search Group unleashed to the pedantic approach favoured by textbooks. It’s far more exciting.

And can you imagine yourself a fly on a wall at the Marketing think tank when they came up with such a slogan? Okay start again, “Only a company is good, if they have people in them.” No, “Inside of a company, they is people, good ‘uns.”, No wait, I’ve got it. “Outside of a dog, a book is a man’s best friend. Inside of a dog it’s too dark to read”, um…

This next one is just pure anarchy and needs no further comment.

It's raining cats and dogs, with a chance of lizzards this evening...

It’s raining cats and dogs, with a chance of lizzards this evening…

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.