Tag Archives: Technical writing

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

twcredo

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

Overcoming DITA’s acceptance hurdles

dita-bird_0This is an appeal to the DITA community: the experts and the evangelists, and possibly the tools vendors as well.

We’ve done a good job selling DITA: after years of slow growth it’s gaining momentum. As it does so, paradoxically, I’m hearing more and more anti-DITA rhetoric. While some of the rhetoric reflects a lack of understanding or even a hidden agenda, some is worth listening to.

I’m thinking of two things in particular that the DITA community often touts as selling points: authors no longer have to worry about formatting, and their DITA content can readily be used for adaptive content — output customized for the audience.

As good as those sound, I don’t see content authors raving about them. We need to understand why that is, and find a way to address it.

Leave the formatting to us

I’ve proudly touted this in every DITA class I’ve taught: Freed from having to worry about fonts, indentations, and other formatting issues, authors at long last can concentrate on content.

Except that a lot of authors like to worry about formatting. Continue reading

Hey, let’s give it a name

The year’s first big winter storm is expected to hit the U.S. East Coast this weekend. You know it’s big because the Weather Channel has given it a name: Jonas.

twc_screen_shot

Screenshot from a Weather Channel video. I remember the weather being dreadful last February. Now I know who to blame: Octavia, Pandora….

A few years ago TWC started naming winter storms as if they were hurricanes — a  practice that amuses some, confuses many, and edifies practically no one. TWC’s explanation of the “science” behind naming winter storms is a technical-writing tour de force, mixing a few high-sounding facts with colorful graphs and a sprinkling of acronyms, and wrapping it all in a thick coating of earnestness.

Anyhow, I got to thinking. If TWC can give names to winter storms, why can’t we give names to the various parts of the technical writing process? Something like these…. Continue reading

Don’t jeopardize your audience: a lesson in clarity

Did you hear about the Final Jeopardy answer that stumped all of the contestants, causing them to finish the game in a 3-way tie with $0.00? (On Jeopardy, unlike other quiz shows, contestants are given the answers and asked to supply the questions.)

Here’s the answer. Spoiler alert: You’ll find the correct question at the end of this post.

jeopardy19n-2-web.jpg

Source: Sony Pictures Entertainment

Got that? Like a lot of good Jeopardy answers, this one requires you to blend your knowledge of disparate things — mid-20th century history and the locations of presidential libraries.

But unlike good Jeopardy answers, this one is just too convoluted.  It takes a lot of untangling just to figure out what they’re looking for. The name of an event? Umm, no. The name of a president? No again.

They’re looking for the name of a city. See it there, buried in the middle?

Watching all 3 contestants walk away empty-handed should serve as a reminder to every technical communicator: keep it as straightforward as you can. Even (especially) when you’re describing things that are complicated. Use an uncomplicated sentence structure in which the subject and predicate are easy to find and all key ideas receive the proper emphasis.

Otherwise your audience will walk away empty-handed.

The question to the answer: What is Little Rock, Arkansas? Did you know it? (I did.)