Cooking up good technical communication

I got home this evening with no idea what I’d have for dinner. I looked in the refrigerator, and didn’t see a lot to encourage me. I opened and threw away a lot of furry things, and ended up with

• an onion
• some cherry tomatoes
• the heel end of a roast
• a rather dispirited bell pepper
• a small potato

With about three more ingredients, I’d be able to…

…Beat my head against the wall, because I’d still be facing the problem of “What the heck am I going to make out of THIS?”

Frame the problem another way: What cuisines start with onions and tomatoes? Mexican, Italian, and Indian came to mind. Now add some bell pepper, potato, and meat – to me, this suggests a curry. Add some ginger, cumin, turmeric, and hot pepper. Set it to simmer.

An hour later, it’s delicious.

Technical communication works that way, too. Sometimes you start a new job looking at a collection of ingredients that don’t seem like enough to get the job done – an authoring tool, an intranet used by a few people, a pile of bloated manuals, a kind and earnest subject-matter expert who tells you it has to be done this way because it’s always been done this way. 

With about three more ingredients, you’d be able to…

…Beat your head on the wall, because you’d still be facing the problem of “What the heck am I going to make out of THIS?”

You can see what the last person made, but you need to know whether it was a satisfying dish. What has the process been? Where are the pain points? What are the private frustrations of each stakeholder? What have the customers been saying? The answers will give you an idea of what to cook up with the ingredients on hand.

Season it generously with the things you know will help: An assessment of the library that you’ve inherited, and (if necessary) a redesigned information architecture. Some basic project-management tools, such as a project plan and a project tracking tool. A special category in the bug-tracking tool to let people report deficiencies in the things you publish. 

Let things cook for a while. Let your stakeholders have a taste whenever they ask. Pay careful attention to their feedback; let them see that you want to serve up something to their taste. But remember that you’re the cook.

Mockingbirds and Robins: How We Face New Ideas

If you live in the more temperate parts of the USA, you probably see robins during the warm months. Their annual return may be what tells you that winter is over. But I live in Central Texas. This is where robins spend their winters.

This morning my back yard is the scene of an epic battle. The robins are here in force, and the mockingbirds are none too happy about it. Every mockingbird in the yard is chasing robins. It's futile. There are far more robins than mockingbirds. They might as well be trying to mop up marbles – you can move them around that way, but it won't get rid of them. But mockingbirds never, EVER give up. In a couple months, the robins will decide it's time to head north again. They'll leave when they're good and ready. When they do, the mockingbirds will do a mockingbird victory dance, yelling the mockingbird equivalent of "We won! They're gone!"

It won't occur to the mockingbird warriors that it's in the nature of things for the robins to leave when spring rolls around, and all the effort the mockingbirds put into making the robins feel unwelcome had nothing to do with it.

Have we ever seen this before?

A new management fad sweeps in like a flock of birds. We complain about all the stuff plopping down in little splats. We shoo the new thing away, like mockingbirds chasing robins. We think of ingenious ways to avoid it, and when these don't work, we complain some more.

Ideas succeed or fail on results.
After a bad idea fails on results, it goes away as inevitably as robins fly north in the spring. Those of us who have been complaining about it decide we have been successful in resisting it, and feel encouraged to complain and resist when the next unpalatable idea comes along. "Keep on chasing those robins, and they'll go away," we tell ourselves, treating the episode as validation for complaining. But the fad didn't go away because we complained about it. It went away because it didn't deliver the anticipated results.

Try this: The next time a bad idea comes along, see what happens if you don't complain. See what happens if you treat it as a good idea and go along with it as well as you're able. See what happens as the results come in. If it's truly a bad idea, it will fail on results; and if it turns out to be a good idea, you won't be one of the whiners who opposed progress.

The direct damage from a bad idea is usually transitory; the most lingering damage is the fact that so many people take it as a license to complain. Think about it: What kind of workplace do you prefer – one where people give ideas a chance and let results speak for themselves, or one where people complain?

This year, I'm going to do my best not to be a mockingbird. The robins are going to leave in their own time, whether I raise a ruckus or not.

Seeing my work through others' eyes

A few days ago, I got to the office and popped in for a look at BlobCo's intranet - meaning it was a pretty typical morning. At least it was until I spotted a post by our trainer.

The trainer's post was a compare-and-contrast piece explaining the difference between training and documentation. Having been unaware that there was any confusion on this point, I was interested enough to read it. Sometimes I find out that my assumptions (such as "everyone knows the difference between training and documentation") are completely mistaken, and I was willing to believe that I had reached one of those moments.

Except that wasn't what was going on.

The post mentioned training briefly, then focused on what documentation is: It's reference material, it's purely descriptive, it's not something you read all at once.

I fully agree with that last one. But the first two aren't an accurate depiction of the work that I've focused on at BlobCo: Task-based help. It's not about describing the menu items and buttons. It's about getting people from being stuck to getting our product to do what they want it to. It's also about jogging people's memories when they've forgotten what they learned in the training sessions.

I took away a handful of insights from this:

• Lots of people still don't know what I really do.
• Lots of people think they know what's in the documentation before they even look, so they don't bother to look.
• Even if you're positive that you know a thing, it's always worth researching it before you write about it...because you might still be wrong.
• It's really easy to irritate people by mischaracterizing their work.
• Getting irritated means you're paying attention to the wrong things.
  
• Having your work mischaracterized is a gift: it's your signal that you need to get better at your 30-second explanation of what you do and how it contributes to your organization's overall goals.
  

OK, that feels better. I got some constructive ideas out of this, and I came out of it with my sunny side up.

Stumbling, falling, getting back up

The Tribal Knowledge project.
Oh yeah.

Late last year I was given the charge to manage a project to document troubleshooting processes that exist only in the minds of a handful of tech support gurus. It will help the support group to train new support people more effectively, and it will take the pressure off the gurus, who currently spend a lot of time solving the same problems over and over.

We put the project aside at the start of the year, because things were getting busy. After the really busy period, we met in February and agreed to cut down the scope of the pilot phase. People were still too busy to meet regularly to create the half-dozen flowcharts we envisioned as the pilot phase of the project; a lot had been postponed during the big thrash in January. We would do just three flowcharts. We met again a couple weeks later and cut the pilot phase to the smallest possible effort: a single troubleshooting flowchart, to be shared and evaluated, tweaked and published on the BlobCo collaboration site. I could almost hear an imaginary sportscaster exclaim, "Oh, that was a nasty stumble - let's see if they can recover."

A very skilled tech support person volunteered to build the flowchart, and emailed it out for comments a few days later. Someone provided constructive technical review comments. The flowchart owner got very busy and didn't have time to make the changes. I urged her to post it in its unfinished form and let others collaborate on completing it.

Nothing happened.
Imaginary sportscaster: "And we've got a player down on the field - it looked like she was going to recover from that stumble, but she's down."
What went wrong?

The concepts of working laterally, collaborating, and doing stuff because it's the next step in the plan instead of because the boss said "Do it" are central to this project. They're also markers of a mind-set that was once strongly discouraged at BlobCo. I could see from early on that the organization was recovering from a nasty bout of 1980s-style command-and-control, but I didn't realize how deeply it had scarred people. Everybody is too busy with their regular work to participate in this subversive, risky project, because "too busy" is the perfect reason — it's true, and it shows that people's priorities are right: We can't do this strictly internal project because we've got customers who need our help.
Because it takes us a long time to help each customer.
Because we've never documented and shared our troubleshooting knowledge, so we have to go ask somebody instead of looking up a troubleshooting flowchart in some central place.

We are like lumberjacks too busy cutting down trees to stop and sharpen our axes.

I asked the VP sponsoring the project to help me figure out how to get it back on track. He proposed a way: Authority would be exercised. People would be given assignments. There would be rewards at the end.
This didn't feel right.

Six of the couple dozen participants showed up at the next meeting. Several people had mysteriously taken the day off. I was frustrated. But the passive resistance and my frustration both validated my sense that we were taking the wrong approach. My sponsor bowed out and told me I needed to enlist a new project sponsor, suggesting two people who were well-placed to do this.

Time to seek out a Jedi master. I talked to Cat Herder.

"You've got too many people on this project. You need to drop the ones who aren't passionate about it," said Cat Herder, who went on to give advice that resonated strongly with my original sense that the project can only succeed if people WANT to participate. In just a few minutes, I heard several ideas about how to foster the creative, collaborative environment that will set people up for success; and we roughed out a plan for reshaping the Tribal Knowledge project and getting it moving again.
I am listening.

You have to fall down before you understand what it means to get up, and it helps if someone offers you a steadying hand.

I may have just connected with the next great teacher in my life.

You just might find...You get what you need

Sorry, I've had the Rolling Stones rattling around in my head all evening; hence the title.

A lot has been said about the Society for Technical Communication lately, so I trust you to forgive me if I don't beat that dead horse. Instead, I'd prefer to flog one of my own favorite equine corpses, Getting What We Need From The Software Guys.

Late last week I started what I thought would be a minor update to the product help for MumbleCo's flagship product, Big Software. One of the changes was that things had been streamlined. They had eliminated all cases of multiple paths to one task. Excellent! I slammed through all the task topics in the help and updated the navigation. Easy-peasy.

Except...

As I updated the top-level navigation in each task topic, I realized that in addition to the top-level changes in the software - tabs moving from one place to another - the entire user interface had been streamlined. Just about every gol-dang screen. Gone were the buttons that hid drop-down menus; now we just had clickable links right out in front of God and everybody. Extra clicks had been removed from nearly every task. This was a huge improvement in usability, but suddenly the help update stopped looking minor.

I have worked with many technical writers who would have stopped right there and gone up in a tight spiral, yelling variations on "How could they do this to us?" You know the routine.
"Why didn't they tell us they were making this change? Are they TRYING to mess with us?"
"OMG, they never tell us anything!"
"Code guys are so self-absorbed!"
And my favorite, "They have no respect for WOMEN!"
I skipped all that. Here's why:

Taking all these gripes in reverse:
I'm a woman, and no developer has ever shown me disrespect. So I have doubts about the whole misogyny thing. Next!
Developers have their own priorities and their own way of seeing the world, just as technical communicators do. Next!
They never tell us anything - OK, do we ever tell THEM anything? Such as how we work, what we need, what our schedules look like? Generally, not until we fail to get what we want. Next!
They didn't tell us about this stuff because it looked pretty trivial to them. Why should they bother us over something as trivial as taking a pull-down menu and making all the choices visible all the time? They don't know how we work, so they don't realize that's important to us.

So I skipped the yelling step and went straight to the next one - solving the problem.

The head of the software development team walked by my desk at an opportune moment. I hollered his name: "Code Jedi!"
"I didn't do it!" he yelled back, speeding up.
That's my line, but I didn't call him on it. "I know you didn't, and that's the problem," I hollered back.
That stopped him. "What's up?"

I explained that I needed information I hadn't been getting, and that I knew the reason I wasn't getting it was because Code Jedi's team didn't know that I needed it - I hadn't ever asked explicitly. As a consequence, I was trawling every single task topic in the help for Big Software to check it against the Big Software user interface, because a lot of things had changed while I wasn't looking.

I explained that while the changes streamline the tasks that people do using the software, those changes make the help inaccurate. People who are comfortable with software in general won't be troubled in the least by the changes, but those are not the people who resort to the help. If I don't know about a change in the sequence of things that people have to click, then the people who rely on the help to build their confidence will have that confidence shattered when the help doesn't match what they see on the screen. So I need to know about even tiny changes in the user interface. If it's connected to a reported issue, I'll find out, because I work from the issues tracking system just as the software development team does. But if it's so minor that someone fixes it on the fly, I may not find out.

Code Jedi got it. All of it.
"First of all," he explained, "We don't do ANYTHING unless we're told to do it. So it doesn't happen unless it's connected to a reported issue. But you're right that we're not giving you the information you need. What we can do is put a check box in the issue reporting form, to flag whether the fix affects the user interface."

"That sounds good, but what I'd really like is before-and-after screen shots."

Code Jedi thought about that. "That would be hard. The developer would have to have access to before-and-after environments. Or they'd have to remember to do the screen shot before they started."

"OK, I could probably get what I need if I could just get an 'after' screen shot reliably."

"We could do that. Make the issue tracking form include the checkbox that flags a UI change, and attach a screen shot if it's checked. That would not add a lot to the guys' workload. We could do that. And QA could check whether the UI changes and bounce the issue back if one of my guys forgets to attach the screen shot you need."

OK. That would give me everything I need.
It took five minutes of friendly conversation to devise a process to ensure that I always get the information I need. "Thanks, Code Jedi. There will be chocolate-chip cookies in the near future."

"Awesome."

Problem solved.
And I've got all the ingredients for chocolate-chip cookies on hand.

Over the Threat-Level Rainbow

September 11, 2001 didn’t change everything, but it changed a lot. We got a big new federal agency, the Department of Homeland Security; and one of the first things it gave us (aside from qualms about a name that evoked rhetoric about “das Vaterland”) was a system of communicating “the threat level” using the rainbow.

Before I say anything more, a word to the communication professional who was given the job to develop a system for telling us about the terrorist threat level in a clear way:
I am certain that what you came up with was great to start with, and that people way up your chain of command - people with communication skills on a par with those of compost heaps - told you to say it their way. We'll never get to see how you rose to the challenge so masterfully, but we know what it's like to be edited by a committee of people who couldn't write their way out of a wet paper bag with properly sharpened pencils. This post is not about you, it's about them. You can show them this post if you think it will help.

The threat-level rainbow instantly became joke material.
Why?

There were a lot of reasons, and all of them provide lessons for technical communicators. To recap, here ‘s a link to a page with a graphical explanation of the system. This is on the Department of Homeland Security web site:
http://www.dhs.gov/files/programs/Copy_of_press_release_0046.shtm

Here's the text in the graphic:

• (Red section) SEVERE: Severe risk of terrorist attack
• (Orange section) HIGH: High risk of terrorist attack
• (Yellow section) ELEVATED: Significant risk of terrorist attack
• (Blue section) GUARDED: General risk of terrorist attack
• (Green section) LOW: Low risk of terrorist attack

I think this graphic probably sent 90% of technical communicators up in a tight spiral. We had a lot of fun trying to top each other in pointing out what was wrong with it, because that’s what we do. But now that the DHS has decided to retire the threat-level rainbow, let’s see what lessons we can take from it and apply to our own work.

What should we do better?

Accessibility.
The colors were only meaningful to people with full-color vision. Although around 90% of the sighted population has full-color vision, using colors as the main keywords excluded TENS OF MILLIONS of Americans.
Do it better: Color is great, but if your audience might include people who can’t perceive it accurately, don’t use it as the main way to make your point.

Expectations.
As kids, we learn that the color sequence in the rainbow is red, orange, yellow, green, blue, purple. When we see red – orange – yellow, we expect the next color to be green. The threat-level rainbow breaks our mental model: After yellow comes blue. So lots of people had trouble remembering what blue meant.
Do it better: Choose metaphors and symbols that are intuitively clear.

Metaphors that work.
The reason the threat-level rainbow goofs up green and blue is almost certainly that green means everything is OK, and that definition is not open to renegotiation. Rather than stopping and finding a visual metaphor that provided a meaningful sequence of five elements, they broke the metaphor after the third of five messages.
Do it better: Broken metaphors don’t help your audience. If your metaphor breaks at any point, find one that works better.

Intuitive scale.
Most people would recognize hot – warm – tepid – cool – cold as a five-point scale; but the keywords severe, high, elevated, guarded, and low don't form an obvious sequence. Low isn’t the opposite of severe, high isn’t the opposite of guarded.
Do it better: Don’t invent a scale; find one that expresses the continuum you’re talking about.

Appropriate scale.
The confusion about what the blue and green levels meant was moot, because the USA has never been at either level.
Do it better: This is akin to explaining “DANGER” notices in a manual that doesn’t have any. Don’t. Who has time to do work that won’t be used?

Tight editing.
Take another look at the list of threat levels. Why say “HIGH: High risk of terrorist attack” when you could say “HIGH risk of terrorist attack” instead? And what about “GUARDED: General risk of terrorist attack” – what does that even mean?
Do it better: Phrase things consistently, use as few words as you can get away with, and make each word convey your meaning precisely.

Warnings we can respond to.
Any time you’re at an airport in the USA, sooner or later you’ll hear an announcement that says the threat level is orange. George Orwell and Robert Anton Wilson would be proud: It’s an announcement calculated to make us tense up inside, but there’s never any advice about how to identify, evaluate, respond to, or prevent threats.
Do it better: If you’re going to warn people about a hazard, tell them how to stay safe.

We could delve into the implications of setting up a multi-level system to inform us of threats and then leaving the threat level unchanged for five years, but that’s outside the realm of technical communication.

The Tribal Knowledge Project: Facing Reality

A couple dozen of us at BlobCo have started a project to collect and share the deep, secret knowledge of the gurus on our technical staff - those amazing people who can get to the bottom of any customer's problem, no matter how intermittent or bizarre. They know things the rest of us don't, and we'd all be more valuable to our customers if we could learn what they know.

I've been given the extraordinary privilege of coordinating this effort. I don't think of it as leading, because all I'm doing is facilitating the process of deciding what to do and how to do it. Later I'll organize the information that comes out of the project. These are things I do anyway, as part of my job, so it doesn't feel like I'm doing any leading. Maybe steering a little, since I have deep, secret knowledge of how to collect and present information; but it's the folks in the front of the canoe who will keep us from smashing up on the rocks in the places where the water flows fast.

We have about one big mental breakthrough a week. I don't know about you, but that's enough to keep me really excited about the project. At our last meeting, the big idea was to work in teams of two or three to work out the process for solving each of the problems on our list.

But things are getting busy at BlobCo. We have a product release coming up. On top of that, everyone who's not involved in that is getting ready for a big conference. And this project hadn't even been imagined when people figured their headcount requirements for the year.

One of the technical services people came to me quite upset that she wasn't going to have time for the project for a while. Time to deal with reality. Since it's crucial for me to keep the project from becoming a burden, I let everyone know we were calling a halt to work on the project until after the conference and product release. When I updated the VP of Mumble on our progress, I explained this decision, and he agreed - he needs his people to focus on the company's current priorities.

The Tribal Knowledge Project will go live again next month. I'm looking forward to continuing our adventures.