Tag Archives: Technical writing

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.

 

Advertisements

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 it’s not about my personal preferences. If I want my name on something, I should write a novel.

My job is to make the information 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.

The first all-emoji technical manual

This week the technical communication world is abuzz over the April 1 release of Remco Children’s Bedroom Suite: Assembly Instructions. Written by breakout author Julian Rebusser, it’s the first technical manual written entirely in emojis.

Recently I caught up with Rebusser, Skyping from a very hip coffee shop on the West Coast, for this exclusive interview.

Leading Technical Communication: Welcome, Mr. Rebusser, and thank you for agreeing to appear in my blog.

Rebusser: You’re welcome. I read somewhere online that your blog is influential, and I’m all about building my personal brand.

Tell me about your new book.

It’s got all the instructions for unpacking and assembling a full suite of children’s furniture: bed, night stand, armoire, desk, chair. For a few extra bucks you can even get a lamp

Assembling all of that must require a lot of complicated steps.

Yes. And when I wrote it as a conventional manual, it was like 20 pages of crap

What inspired you to write an all-emoji technical manual?

I had an epiphany one morning, waiting for the barista to brew my double-shot caramel macchiato

Wow. What was that like?

Well, for the first time ever, I thought about my audience.

You hadn’t thought about your audience before?

Of course not. Great writers don’t think about their audience. They think about cool, hip ways to express themselves. But for 2 or 3 minutes that morning, for some reason, I thought about my audience. And I realized something.

What did you realize?

Well, who usually assembles a furniture set for children?

Their parents, I suppose.

Right. And who are those parents?

I’m not sure I follow.

They’re Millennials! Digital natives. People who don’t read books

They don’t read books?

Of course not. They don’t like to read anything. I saw that in an article online.

And so the children’s parents….

Right. If I gave them words they’d never read them.

So, instead, you gave them….

Emojis! Millennials love emojis. I saw that online too. And I knew I was perfect for the job because I speak fluent emoji.

What happened next?

In no time my 20-page draft was down to 2.

Can you give me an example?

It used to take a whole page to explain how to bolt the legs to the bed.

And now?

Now it’s boltlegslegstwobed

I — I’m speechless.

I presented this last week at Write the Docs, and they were speechless too.

So now everyone knows you as the first all-emoji technical writer. What’s next?

Well, it’s all still hush-hush. Can you promise to keep a secret ?

Sure.

Next year when Remco rolls out its do-it-yourself flower garden, I’ll be there with an emoji-based augmented-reality experience. I’m calling it Pokemon Grow.

I can hardly wait.

It’ll totally blow your mind.

Yeah, I’m sure it w– mind blown

Timing is as important as delivery

Dear technical writer:

Your content is well-written and accurate. But what happens if you put it into your reader’s hands at the wrong time?

This is what happens.

 oscars17.png

At last night’s Academy Awards ceremony, Warren Beatty and Faye Dunaway came onstage to present the award for Best Picture.

When it came time to announce the winner, the card said

Best Actress
Emma Stone
La La Land

Beatty hesitated. Dunaway read the only thing that made sense in the context: the name of a film, La La Land.

It wasn’t until several minutes later, during the acceptance speeches, that the mistake became known. Beatty and Dunaway had been given the wrong card. The Best Picture winner was actually Moonlight.

Dear technical writer:

You might not be embarrassed in front of tens of millions of people. But when you provide the right content at the wrong time, no matter how good the content is, you’ve betrayed your readers.

As every good actor knows, timing is every bit as important as delivery.

Video source: New York Times

Where do the technical writers fit?

The other day Sarah Maddox posed the question Where do technical writers fit in an organisation? It’s a question my colleagues and I have bandied about for most of my 30-plus years working in technical communication.

The answer has evolved during those 30-plus years. And it’s tempting simply to throw up my hands and give the standard consultant’s answer: it depends.

smaddox

Sarah, like all of us, is looking for a place to fit in

Sarah doesn’t advocate for any one answer, either. Instead, she deftly states the case for including technical writers in each of these parts of the organization:

  • Engineering and product management
  • User experience (UX)
  • Support
  • Marketing
  • Developer relations

Here’s what I make of it.

We’re not an island

There’s one place in the organization where the technical writers definitely should not be, and that’s off by ourselves.

I didn’t always feel this way.

Early in my career, when technical writing was still being defined as a profession, it was important for the writers to establish an identity as a team and emerge from the backwaters of wherever they’d been placed on the org chart — usually in product development.

In companies that formed separate technical writing teams, the writers were better able to collaborate on tools, training, and best practices. Their managers could fight for a place at the table alongside development, marketing, and support.

The separate-team approach was what I experienced at IBM, and it wasn’t until maybe the mid-1990s that we, as a profession, had evolved past it. Continue reading

Eluding the curse of knowledge

This week’s Tighten This! game exposed a pitfall that good technical writers learn to identify and avoid: the curse of knowledge. Let’s talk about how that plays out in our day-to-day work.

two heads explaining and thinking differentlyThe curse of knowledge strikes when we become experts in the subject we’re describing, and we forget that others — especially our readers — don’t share our expertise. What’s become obvious to us, isn’t at all obvious to them.

Our subject-matter experts have the curse of knowledge. Our readers count on our not having it.

Mark Baker says that the antidote to the curse of knowledge is domain awareness:

Domain awareness means not only knowing the subject matter of your domain well, but also understanding your domain as a domain and its place in the universe. It is only in a state of domain awareness that you act as a useful and reliable tour guide to your domain.

In practical terms this means putting your subject matter into the context of what your readers already know. It means giving them stories and signposts so to help them relate the new ideas and new skills to what they already know..

As you move from novice to expert, you must never forget that your readers need those stories and signposts.

Day in and day out, how can you elude the trap of the curse of knowledge? Continue reading

What’s your leadership story?

monster.png

Monsters are part of Harry Potter’s world. Some leaders would like us to think they’re part of our world too. (Image credit below)

In the run-up to last June’s Brexit referendum, J.K. Rowling wrote a brilliant piece about storytelling:

“I’m not an expert on much, but I do know how to create a monster,” she began, going on to say that all political campaigns tell stories and that one side in the referendum — the Leave side — had worked especially hard to create monsters, or villains.

Former British Prime Minister Tony Blair, writing a day after the vote was taken, explained the outcome by saying the populist Leave side had told its story better than the political center — the Remain side — had:

“The political center has lost its power to persuade and its essential means of connection to the people it seeks to represent.”

He didn’t say that Leave had a better story. He said they told it better.

In politics the spoils often go to the best storyteller.

I’ve found that in leadership in general, the best storytellers make the most effective leaders.

Beginning, middle, and end

A story has a beginning, a middle, and an end. For many leaders, including politicians, the beginning and the middle are simply a recap of the listeners’ current circumstances.

The end, in politics, is often about the bad things that will ensue if you vote for the other side. (Enter the monsters.) In true leadership, the end is about the good things that will happen if you follow me, or if we work together.

An emotional connection

A story makes an emotional connection with the listeners. Too often in today’s politics that connection is rooted in fear. In leadership the best connections are rooted in shared hopes and in a sense of cohesion, of belonging. We’re in this together, and together we’ll succeed.

Linking technical writing and leadership

Several of us, notably Mark Baker, have pointed out that storytelling is essential to technical writing as well. We guide our readers from a beginning point through a set of steps (the middle) to the desired outcome (end).

We try to connect emotionally with our readers: gaining their confidence, reassuring them as they move through the steps, and congratulating them when they finish.

Does it follow, then, that technical writers have an edge when it comes to being good leaders? I think it does, as long as we remember that we’re storytellers and that our calling is to help people meet their goals.

What do you think? If you’re a technical writer who became a leader, did you find that your skill at the one helped you succeed in the other?

What’s your leadership story?

Update, 30 June 2016: My colleague Ray Gallon has broken down the “Leave” story in detailed and illuminating fashion. Highly recommended: The Morning After: Brexit of Champions.

Image credit: Bob McCabe, Jody Revenson, Moira Squier – Harry Potter Page to Screen: The Complete Filmmaking Journey 

DITA adoption: What are the numbers?

I just saw this infographic from IXIASOFT about a subject near and dear to my heart: the adoption of DITA.

Cg_W9ieUoAEuhEC.jpg largeLike so many infographics, unfortunately, this one is a mess. It’s cluttered, with so many elements competing for my attention that I can’t tell what its key messages are.

I don’t expect IXIASOFT to know how to create good infographics. That’s not their business. But I expect them to know about DITA and about the technical writing community in general.

That’s why I’m taken aback by some of their numbers:

  • There are 150,000 technical writers on LinkedIn? Even if that’s a worldwide total, it  seems high. What occupations does IXIASOFT lump under the heading “technical writer”?
  • Only 9,000 say they know DITA? That seems about right – as an absolute number, but not as a percentage of the total. Of the people who are true technical writers, surely more than 6 percent know DITA.
  • 4.0 percent of job ads ask for DITA experience? That’s surprisingly low, considering that by IXIASOFT’s own count more than 600 companies have adopted DITA and a growing number of writers claim to know it. I recall seeing another presentation that put this number in the 10-to-20 percent range, but I can’t place my hands on it. Does anybody have data on this?

I looked on IXIASOFT’s website for illumination. There I found a piece in which Keith Schengili-Roberts put the 6 percent figure into context by noting that only 15 percent of technical writers claim to know FrameMaker. That makes me wonder all the more how broad their “technical writer” umbrella is.

I also discovered that this infographic has been around since at least November 2014. In the earlier version (which you’ll find in Keith’s article) the numbers are slightly different. But they still look suspect.

I’d like to find a truer picture of DITA adoption. Does anybody know of one?

Tell your story, respect your reader

Look at these two maps. They’re based on the same data: population gain or loss by county. But they tell vastly different stories.

In the first map, the graphic artist started with the two extreme values in the data set (-6.3% and +28.7%) and divided the color scale into 5 equal pieces. As a result, all of the counties losing population are lumped together with counties that had no change or that posted slight gains.

usmap1

Source: Pew Charitable Trusts

The map tells us that a lot of counties lost population or held steady, several counties added population, and exactly two (one in the top middle and one near the bottom middle) added a lot of population. Frankly, it’s not much of a story.

Now look at what the Washington Post‘s Christopher Ingraham did with the same data. Ingraham changed the color scheme: blue counties gained population and red counties lost. The color intensity changes for counties that gained or lost more than 1% or 2%.

usmap2.png

Source: Christopher Ingraham, Washington Post

Now you can see a story. Continue reading