Tag Archives: techical writing

Watch out for Survey McSurvface

If you want to improve your product’s documentation — or the whole user experience — there’s a tried and true technique: do a survey. At least that’s what we’ve always been told.

Let me tell you a couple of stories.

The boat


Come to think of it, “HMS Coke Can” might be a more suitable name. (Source: Natural Environment Research Council)

Earlier this week the British government, in the person of Science Minister Jo Johnson, announced that its new research vessel will not be christened Boaty McBoatface, even though that name won an Internet poll with 4 times as many votes as the runner-up.

Evoking memories of Graham Chapman’s Colonel, Johnson declared that the winning name was simply too silly and that a more “suitable” name will be chosen instead.

The bridge

Much the same thing happened in 2006 when Stephen Colbert, in his Comedy Central days, encouraged his viewers to vote in an online contest to name a bridge in Hungary.


The Almost-Colbert Bridge (Source: Wikimedia Commons / Civertan)

Stephen Colbert Bridge won, garnering more votes than there are people in Hungary. Things hit a snag when Hungary’s ambassador to the U.S. good-naturedly informed Colbert that in order to be honored, he would need to be (a) fluent in Hungarian and (b) dead.

Today the bridge is known as Megyeri Bridge because it connects two towns whose names end in -megyer. I’m not sure that’s better than Colbert Bridge. But I’m not Hungarian so I guess it’s none of my business.

The moral of both stories? Surveys and polls can be entertaining. But their results aren’t always useful.

Your customers

Now I know that nobody is going to turn your customer survey into a prank. Still, when you ask your customers what they want, they don’t always know. Their responses likely will be knee-jerk, not reflective of careful thought.

Want a better index? Sure, that sounds good. Bigger icons? Why not? Soon you’ve got a lot of “results” that you can turn into action plans. Yet you’ve missed the issues that truly affect the UX.

The solution? Don’t ask your customers what they want. Instead, ask them how they actually use the product, and ask them what things give them trouble. Do they have difficulty finding the instructions they need? Are the instructions relevant to their work situations? Are there product features that go unused because they’re hard to set up and maintain?

When you ask your customers how they really use your product, then you can use your own know-how to decide how best to make their lives easier.

There’s an even better way, although it’s harder than administering a survey. If you can observe your customers at work, if you can see for yourself where they succeed and where they struggle, then you’ll know exactly where to focus your efforts at improving both the documentation and the rest of the product.

So there you have it.

Surveys that ask customers what they want: too silly.

Surveys that measure the way customers actually use the product: much better.

In-person observation (including usability tests): harder, but best of all.

Tell me about experiences you’ve had improving your products by gathering information from your customers.


We have met the future, and it is us

A lot of bloggers, including yours truly, have spilled a lot of ink (electrons?) pondering the question, What does the future hold for technical communication?

Sarah Maddox, one of the most insightful technical communicators you’ll ever
meet, recently turned the question on its head.


Image source: Sarah Maddox (ffeathers.wordpress.com)

At her keynote address at the tcworld India conference last month, Sarah asserted that the future is technical communication — and then made a strong case for why that’s so.

The summary of Sarah’s talk, and her accompanying slides, are two of the best things you’ll read all week.

Here’s a paraphrase of what she said. Continue reading

Landing your first (or 20th) technical communication job


A job search can be discouraging. Yet prospective employers need to see that you’re confident and optimistic. (Morguefile:jdurham)

I spent an enjoyable and productive Saturday afternoon at the STC Carolina chapter’s Student Resume Clinic. Several colleagues and I gave resume advice and conducted mock interviews with students from local colleges.

(Kudos to the Carolina chapter, especially president Christina Mayr, for putting on such a great event.)

If you’re looking for your first job in technical communication — or your 10th job, or your 20th — here’s some wisdom the students took away from that afternoon. Continue reading

Are we driving or being driven?

On my first or second day in my new technical writing job my manager told me, “The CS [customer support] guys have put together a ‘cheat sheet’ for setting up hardware redundancy. They’d just started working with Pat [my predecessor] to get it published as a user guide.”


Image source: Scriptorium

I looked at the cheat sheet: a 40-page Word file describing what works with what (and what doesn’t), the basic setup process, and several “gotchas” to watch out for. Good, useful stuff. Yeah, our customers would like to have this. I can massage it into a user guide.

But when I investigated further, I found a surprise: about half of the cheat sheet consisted of content already in the product documentation. The CS guys were surprised when I pointed that out to them.

So now we have two things going on: the organization has good information that it wants to deliver to its customers. At the same time we’re already delivering good information, but people don’t know it’s there.

My situation exemplifies two of Scriptorium’s Six Trends of 2016 — two trends that at first sound contradictory but actually are closely related in yin-and-yang fashion. Continue reading

Defining what you and I do

I remember trying to do this in STC without getting too far. Now tekom, the European professional society, has taken a stab at defining the job duties of technical communicators.

Graph showing 7 major areas of competency

Source: tekom

I think they’ve done a pretty good job.

Start with the 7 areas of competence (pictured). These aptly describe, in broad terms, the tasks associated with each stage of the content lifecycle.

Then look at the 27 fields of competence. For example, Content Creation — one of the 7 areas of competence — breaks down into identifying information sources, acquiring and selecting information, using tools to create content, and so forth. You can see these 27 fields in the Profiling Tool, a self-assessment that anyone can take.

Why a competency model?

All of this is a lot to digest. But by and large it reflects our jobs pretty well. In cases where I might quibble with the tekom definitions, it could be because I’m steeped in my own industry and tekom has tried to make the lists industry-agnostic.

Tekom identified four major stakeholder groups for the competency model:

  • Company managers and personnel departments, who draw up lists of job requirements
  • Educational institutions that develop training programs and curricula
  • People who want further education in Tech Comm
  • Practitioners who want to enter the field or enhance their skills

But that’s not all. Continue reading

Mission: TechComm – Making the impossible possible

Ethan Hunt, the hero of the Mission: Impossible movies, is pretty terrific. But he’s got nothing on you, the modern technical communicator.

Mission: Impossible movie posterEthan doesn’t flinch in the face of torture. You keep your cool in a room full of SMEs during a review meeting.

Ethan deals easily with spies and assorted bad guys from all over the world. He speaks their languages and he knows their every nuance. You localize your content for the nuances of an international audience, and you work with translators calmly and professionally.

Ethan is up on all of the latest computer technology, and so are you. (I wonder if Ethan knows DITA?)

Ethan is comfortable working under cover. You work out of the limelight, the project team sometimes totally unaware of the value you contribute.

Ethan’s at his best when on the run, staying one step ahead as killers chase him around the world. You stay ahead of schedule as deadlines run toward you.

And the really scary parts? Hanging on to the outside of airplanes and such? No more scary than when the project manager announces that two features have been cancelled and three new ones added — and the docs are still due next week.

So next time you’re on a project that seems impossible, remember that you’re an action hero. Accept your mission and go change the world.

Postscript: Do you know a good backronym I can use to rename my Tech Comm department to IMF? If so, please let me know.

Review: “Learn Technical Writing” online course from Udemy

Screen shot titled

A screen shot from the introductory part of the course

Udemy recently invited me to try their online course, Learn Technical Writing & Make an Average of $67,910 a Year. As the name suggests, the course is aimed at those who are new to technical writing or who are considering making technical writing their career.

Well-known technical author Dr Ugur Akinci developed the course and provides the audio narration. While I often wished that he wasn’t simply reading the slides, I very much liked his tone: warm, confident, supportive. Continue reading

Watch those connotations

connotation (n.): the associated or secondary meaning of a word or expression
in addition to its explicit or primary meaning (from the Random House Dictionary)

Marli Mesibov has a nice piece, The Meaning Behind Connotations, explaining why content strategists must consider the reader’s interpretation of the content – not just its explicit meaning.

She describes an instance where an Internet marketer used an image that offended a lot of people and then tried to blame the people for taking offense. Then she says:

If the user has a certain connotation with a term (or image), then we as content strategists can’t decide they are right or wrong. It’s our job to accept that connotation, or lose the user’s trust.

Jared Spool tweet: Semantics is about meaning; meaning is important

Words of wisdom from Jared Spool (quoted by Marli Mesibov in her article)

As any good writer knows, you have to own what you write. You’re responsible for whatever meaning is there — whether you stated it explicitly, whether you laid it between the lines, and even whether you put it there by mistake.

You don’t get to decide what meaning the reader will take away. And because it’s a question of trust, it goes to the heart of the relationship between your business and your customers.

This applies every bit as much to technical writing as it does to content strategy, since the technical content you create falls (or should fall) under the rubric of your organization’s content strategy.

So how do you keep connotations from becoming problems? Continue reading

What one thing isn’t Tech Comm doing?

Hand holding a penOn this third day of the third month, I have three questions for you about the Technical Communication profession:

  1. What one thing isn’t Tech Comm doing, that it should be doing?
  2. What needs to happen to get us started doing that one thing?
  3. What are you personally doing about it?

So much has been written and said about how technology is evolving, how marketplaces are changing, how all of us need to learn new skills just to keep up. It can feel overwhelming.

So let’s boil it down. Pick one thing, and use the Comments section to tell me how you, and we, can make it happen.

(Part of the inspiration for this post is a fantastic article by Sara Wachter-Boettcher, Content Amid Chaos, in which Sara advises — among other things — approaching a big problem by starting with just one thing.)

All I want for Christmas is…. (Tech Comm edition)

I’ve been a good little technical communicator all year. At least I think I have. If I’m on Santa’s Nice list and not his Naughty list, this is what I hope he’ll bring:Santa Claus

  • A good understanding of who my readers are
  • User stories or scenarios that accurately describe the tasks my readers are trying to do
  • SMEs who take documentation seriously and make themselves available
  • A doc plan that spells out what everyone expects of me — and what I can expect from them
  • Managers who understand that good technical communication is good for the bottom line
  • Tools that let me create and update content, store content, and (especially) publish content to different formats without turning myself into a contortionist
  • A good editor

Here are some things I do not want to find in my stocking:

  • A brand new release of the authoring software, with major changes to the user interface, right in the middle of a project
  • Overpromising by upper management: “Sure, we can ship all of those features by next month”
  • Silos that make it hard, if not impossible, to develop content collaboratively
  • Last-minute translation requirements (and come to think of it, last-minute anything)

What’s on your Tech Comm holiday wish list?