Tag Archives: Technical writing

Do we understand ourselves?

People don’t understand us. From the first time I met a technical writer, I’ve heard them — I’ve heard us — say that.

Our bosses don’t understand us. Subject-matter experts don’t understand us. Our audiences don’t understand us.

So, at long last, we have a chance to change that. A few days ago on Twitter, an app designer named Louie Mantia put this out to the world:

As Louie’s tweet kept popping up in my timeline — with answers from journalists, lexicographers, and historians — I pondered how a technical writer might answer.

It was harder than I expected.

First take

First I thought of answering Louie’s question like this: Our top priority is writing directly to the people who use the instructions.

Then, in my imaginary dialog, I heard a resounding yawn from the general public: Of course you write for the people who use the instructions. For us. Who else would you write for?

Writing for the audience. While we technical writers trumpet it as a big deal, to our audience it’s so blindingly obvious that it goes without saying.

Second take

So I tried a different approach. Technical writers think in terms of how to use a product, not how the product works.

General public: We know that! It’s common sense, right? I don’t need to know how an internal-combustion engine works. I just want to change the oil.

Third take

crowd of people

Might the people understand us better than we think?

My third try: We work hard to tailor our information to our audience — in terms of both content and media.

GP: Hmm. The tailoring part, again, should go without saying. Maybe we don’t understand why you have to work so hard.

After all, when we get it right, it looks effortless. And when we get it wrong, it looks like we haven’t tried at all.

I began to realize that the skills we technical writers prize the most and discuss the most among ourselves, like audience analysis and media expertise, are things that — in the minds of our customers — ought to be second nature.

When we say that people don’t understand us, it’s not because they don’t grasp our skill set. It’s because they don’t realize how much energy we devote to honing those skills and to reminding each other how important they are.

Why do we need to remind each other of things that are so fundamental? Is it because our perspective is skewed from spending too much time with our work colleagues (especially Development) and not enough time with our customers?

Maybe it’s not that people understand us. Maybe we don’t understand ourselves.

Epilog

I finally did answer Louie’s question about what seems obvious to us but is misunderstood by the general public.

What do you think of my answer? How would you have answered?

Do you think our customers would be surprised to learn how much time we spend talking about things that, to them, ought to be second nature?

 

 

 

 

 

 

 

Advertisements

You might’ve heard…

I’m taking a few days off. But please check out my guest post on Amruta Ranade’s blog, in which I describe a few things you might’ve heard about technical writing.

Thanks, Amruta, for giving me the opportunity to contribute to your blog!

Launching your technical communication career

Last time I wrote about the places you can go, or the different trajectories your career can take, when you work in technical communication.

But how do you get that first job? What qualifications do you need, and what are employers looking for?

Prompted by interview questions from a Tech Comm graduate student, and based on my experience working in the field and interviewing candidates, here are some thoughts.

montage of album covers from 1979

We listened to different music in 1979, and breaking into the field was different too.

I got my first technical writing job a long time ago — in 1979. One thing I know for sure is that your breaking-in story won’t be the same as mine. Things were a lot different then, and I’m not just thinking about the music we listened to. Companies, having realized that technical people didn’t necessarily make good technical writers, went looking for young writers who weren’t necessarily versed in the technology but who could learn it.

Armed with a double-major in English and philosophy, and having a tiny bit of experience with computers, I landed that first job with IBM.

You won’t have the same experience. Your résumé will need to look a little shinier than mine did.

What are the educational requirements for working in Technical Communication?

Follow-up question: Are certain degrees or backgrounds more sought after by employers? Continue reading

Technical Communication: Oh, the places you’ll go!

A Technical Communication graduate student recently interviewed me for a project she’s doing. She asked great questions, and (with her permission) I thought I’d share some of my answers with you.

What does a career trajectory look like in technical communication?

Places_you_go_Seuss

Your career in Tech Comm, and possibly after Tech Comm, will be uniquely yours — shaped by your interests and talents.

Follow-on question: Is there lots of room for growth, or do people need to transition to management after a certain point?

There is lots of room for growth. Just as people follow many paths into Tech Comm, they find a lot of paths to follow once they’re here.

It’s like Dr. Seuss said: you can go almost anywhere.

Where you go in Tech Comm — or where you go from Tech Comm — depends on what you’re especially good at and what you’re most interested in. Continue reading

Is your child texting about technical communication?

Here’s a quick guide to find out:

stack of dictionariesBRB
Big reference books

TMI
Tagging my index

LOL
Learn other languages

NGH
Need graphic here

TTFN
Try this font now

Quill penIDK
Insert DITA keyword

WTF
Write the facts

ICYMI
I corrected your mistakes, incidentally

TTYL
The things you learn

TL;DR
Technical literacy definitely rocks

FTW
Fantastic technical writing

Don’t twist the prose

It’s never too early to plan for next year’s gardening. I just got a new pair of pruning shears, and on the back of the package I found these illustrations:

garden_shears

….accompanied by these instructions:

Don’t twist the scissors in use. If the scissors are in the city Figure C in the way the clock pointer, the two shear bodies will squeeze each otherDamage: if it is twisted to the look of the clock in the opposite of the A, the time of the clockWill produce a gap between the two sides of the plane, and can not ensure smooth trim. Correct useShould be shown in figure B.

Yeah. Wow.

I was tempted to laugh and roll my eyes, and I confess that maybe I did. A little.

But it’s also worth pausing to make a few points — because someone wrote this, honestly thinking they were conveying useful information. Nobody sets out to make their readers’ eyes roll. So what happened here? Let’s think about it.

Don’t overthink

First, I’m pretty certain that the writer, despite the best of intentions, overthought the whole thing. Here’s what they wanted to say: For a smooth cut, always cut straight on. Don’t rotate the shears to the right or left.

But, anxious to make sure no one would misunderstand, the writer inserted cross-references to the pictures and added the convoluted text about what happens if you turn (twist) the shears clockwise or counterclockwise. The added detail, rather than clarifying, only muddled things.

My copy often goes from simple to complex, just like this writer’s. Then, after setting it aside for a little while, I can come back and make it simple again.

Translation matters

Then, when you’re writing content for translation, be sure it’s translated by people who know both the source and target languages. It sure looks like this company cut corners when it came to translation. (Maybe they twisted their shears counterclockwise while cutting. Who knows?)

I’m certain that this copy looked a lot better in the source language than it does in English.

Also, when writing for translation, be sure the writer and the translator are working with the same authoring tool. It’s likely that those crashed-together words, like otherDamage and clockWill, resulted from a writer saving the copy in one tool and a translator opening it in another.

Verify, verify, verify

The manufacturer knew they’d be selling their product in a large English-speaking market. Wouldn’t it be nice if they’d usability-tested their instructions — or even if they’d simply verified them with one English speaker?

Perhaps it seemed like an unnecessary expense, or too much of an inconvenience, to verify the instructions. Or perhaps someone simply said We don’t care — just ship it.  Whether that decision will have negative consequences, in the form of damaged customer loyalty or decreased sales, I don’t know. (Very possibly it won’t, which is why someone said We don’t care.)

The decision certainly has resulted in embarrassment for the manufacturer. Can you put a cash value on that?

Reaching your audience through empathy

On Tuesday, January 23, I’ll give an online talk — along with my colleague Christina Mayr — about empathy and how you can use it to connect technical documentation with its audience. Our talk is part of the “Writing Well” conference.

I hope you’ll consider joining us.

Our talk

man-in-the-mirror

In the mirror exercise, you and another actor (think: your reader) follow each other’s moves (credit: whatshihsaid.com)

Audience analysis is at the heart of what technical writers do. But what makes an audience analysis truly successful? Empathy. Customer empathy spans more than customer service; in fact, it’s most needed long before a user even calls for help. By employing empathetic techniques – for example, monitoring customer support cases to find pain points and improve documentation to address them – you help your users  trust your documentation and seek it out before calling customer support.

Our talk, Improve Documentation Usage with Customer Empathy, will show you how to acquire user empathy and effectively create empathetic technical information. It will discuss several empathetic techniques you can use in your organization to start writing with a better understanding of your users’ pain. We’ll also discuss the case studies, collaboration, and user outreach Extreme Networks performed and the results of these activities.

The event

IDEAS conference logo
The “Writing Well” conference is a two-day, online event that’s put on by CIDM, the Center for Information–Development Management. CIDM brings together managers in the field of information development to share information and new ideas.

The “Writing Well” conference invites you back to basics as we explore what defines good documentation in today’s structured, topic-based environment. What does it mean to write well? What characteristics predict whether or not content will be usable and understandable? Where should we be spending our time? What strategies help authors produce content that users willingly turn to first?

I look forward to connecting with you there.

Informing the public, responsibly

The recent flooding in eastern Texas has engendered a lot of news articles. This one from ProPublica stands out because, in addition to covering a topic of interest, it has all the hallmarks of excellent technical writing.

Let me tell you why.

The lede is up front and to the point

The headline itself conveys the major points: Houston’s Big Dams Won’t Fail. But Many Neighborhoods Will Have to Be Flooded to Save Them. Then, in three brief paragraphs we learn that people are afraid the dams at the Addicks and Barker reservoirs will fail, which would flood much of the city, but despite their fears the dams are safe.

The map is well drawn and emphasizes pertinent data

You can see at a glance the seriousness of the situation. There are the reservoirs, and there are the built-up areas adjacent to them and sometimes inside them. (Yes, inside them. Developers have been allowed to build houses within the boundaries of the reservoirs, on land that — most of the time — is above water level.)

Map showing Houston reservoirs and developed areas around them

Map source: ProPublica

The critical spillways (pink dots) are a bit hard to notice, but they’re called out in the article text.

The spillways, the reservoirs, and Buffalo Bayou, the critical waterway to downtown Houston, are labeled. Less essential details are not.

Background information is explained succinctly

On the assumption that most readers aren’t familiar with Houston’s hydrologic history, the writers provide brief summary information, at pertinent points in the story, about why the two reservoirs were built and how the dams are supposed to work.

Content is organized logically, in short sections

Each section heading is a question, like

  • What are the Addicks and Barker reservoirs? and
  • Why are the spillways a big deal? And what will the impacts of using them be?

The questions build on each other. And unlike with most “frequently asked questions” pages, they’re questions that people actually would ask.

Then each section answers the pertinent question in a few easily digestible paragraphs.

The writing is direct and in the active voice

Picking a paragraph at random:

As of now, the Army Corps says there’s enough excess water in the Addicks Reservoir that some of it is flowing around (not overtopping) one of the auxiliary spillways. The agency originally thought water might also have to flow around the spillways for Barker Reservoir, but now projects that will not be necessary as long as the weather stays good.

The tone is balanced

The article’s tone is businesslike yet reassuring. It reinforces the headline: although this is certainly a big deal, and although people who live near (or in) the reservoirs are going to experience flooding, there’s no cause for general panic.

It’s written collaboratively

Don’t miss the byline. Four different writers are credited for the piece: Kiah Collier of The Texas Tribune, Neena Satija of The Texas Tribune and Reveal, Al Shaw of ProPublica, and Lisa Song of ProPublica. Perhaps one of them, or perhaps an unnamed editor, deserves credit for pulling together everyone’s contributions into a single, coherent piece with consistent tone, vocabulary, and writing style.

I tip my hat to all of them for providing the public with information responsibly and in the proper context.

Postscript: I’m always happy to call out instances of good technical writing that I see in general-interest newspapers and magazines. (Here’s another example, about a different topic.) Do you know of any examples? Please share them in the comments.

 

It’s not your text

Hey, wow. I was looking on the internet and — what do you know? — I found a list.

Yes, I realize that the internet is full of lists. Many of them exist simply to entice us to click. A few might entertain or inform, and then I forget them in 5 minutes.

A very few are worth recommending. One such is this list of rules for editors, compiled by the Baltimore Sun‘s John McIntyre. If you’re in any part of the writing business, hurry on over to The Sun and take a look.

I lingered long over Rule 4: It’s not your text.

You are in the middle of things. You have a responsibility to assist the writer in achieving their purpose. You have a responsibility to the publication to maintain its standards and integrity. You have a responsibility to the reader, the party most commonly overlooked in these operations, to meet their needs of clarity and usefulness. Your personal preferences are subordinate to these responsibilities.

quill penSo it is with editors, and so it is with technical writers as well. We have a responsibility to the company we represent, to maintain its standards and integrity (to the extent it has them), and to present its products in such a way that our readers can use them effectively.

We also have a responsibility to the reader, to meet their needs of clarity and usefulness. This is our paramount responsibility, because this is the one we have to get right. We might get away without perfectly reflecting the company’s style or brand image, or without perfectly describing the product’s features. But if we don’t meet the reader’s needs, so that they stop reading and walk away (or dial tech support), we’ve failed completely.

stone bridgeI’ve heard the technical writer described as the bridge between subject-matter expert and reader. I used to bristle at that metaphor: I thought it implied a passivity on the part of the technical writer, as if we were nothing more than a conduit carrying information from one actor to another. “People walk on bridges,” I remember complaining.

Now, in my old age, I’m more comfortable with the bridge metaphor. Maybe I have a higher opinion of bridges: some of them are engineering marvels, and even the simplest ones are mighty useful. But mostly, I think, I better understand that it’s not my text.

Yes, I play an important role in the transaction between expert and reader. But I’ve come to understand that part of my role in that transaction is to get lost. If I want my name on something, I should write a novel.

My job is to make the text good, and that’s nothing to sneeze at. But it’s not my text.

The technical writing beat

At a recent STC networking event, the woman across from me said she was a police officer and wanted to find a job in technical writing.

copwriter.pngShe’d come prepared to make her case. As a cop, she said, I write reports all the time. The reports have to be factual and clear. I reckon I’m already doing technical writing.

Good point. What else you got?

I’m always explaining things to people. How the law works, what they can and can’t do, and why. I deal with people from all walks of life. Many of them don’t speak English as a first language. I have to size up each person and tailor my message so they’ll understand.

Sounds to me like you’re pretty good at audience analysis.

She’d sold me on the parallels between police work and technical writing. It was something I hadn’t considered before – even though I’ve told my students for years that the best exemplar for technical writers is a dogged detective who keeps asking questions until the case is solved.

columboI’ve worked in this profession a long time and met colleagues with all kinds of backgrounds. My encounter with the police officer reminded me that, even though people have followed many paths into technical writing, there are more trails yet to be blazed.

Did you follow an unconventional path into technical writing? Are you even now trying to enter the profession with a background that, at first glance, might appear to have little in common? If so, I’d love to hear your story.  Drop me a line or respond in the comments section.