Tag Archives: Technical writing

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

The technical communicator’s credo

What does it mean to be a professional technical communicator in 2016? What will it mean to be a professional technical communicator over the next decade?

Hand holding a penAfter pondering those questions I came up with this credo:

I serve my audience. I strive to know as much about them as I can, and I supply them with the information they need, in a way that’s appropriate for their context. (Or, as Sarah Maddox put it: in the language that they understand, anywhere, anytime, anyhow.)

I serve my employer. While always behaving ethically I work to advance the interests of their business and represent them to their customers and to the public as they see fit.

I represent my profession. In my dealings with subject-matter experts and other colleagues, I respect both my work and theirs. I never give them reason to question the value of the work I produce.

I constantly seek to learn new things, while discarding techniques and ideas that have become outmoded. I understand that mastering new tools and techniques, and recognizing and adapting to change, are part of what it means to be a professional.

What do you think? If you were to write a professional credo, or if you already have one, what would it include?

twcredo

Rethinking RTFM

Poster: Keep Calm and RTFM

I still appreciate the humor behind RTFM. But it’s not the way I actually feel.

RTFM. Read the [bad word] manual.

As in, “I don’t know how to do this.”
“Did you look at the instructions?”
“No.”
“Well [rolling eyes], why don’t you read the….”

RTFM has been a byword among technical communicators for as long as I’ve been hanging out with them. (That’s more than 35 years, by the way.)

RTFM reinforces the idea that documentation is important, an essential part of any product.

But RTFM also betrays exasperation and insecurity. We — as a profession — might sound smug when we say it. But inside we’re thinking, Why don’t people don’t like to read instructions? We see it as a rejection of what we do, and ultimately of us ourselves. It stings.

It’s time to rethink RTFM. Continue reading