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.

The Tribal Knowledge Project: Getting off the ground

When the VP of Mumble approached me about capturing the knowledge floating around in his technical support staffers' brains, I realized instantly that I knew what to call this kind of project. But for political reasons I don't dare call it what it is. So for now I'm not calling this project a knowledge base; I'm calling it the Tribal Knowledge Project. The phrase seems to resonate with the people involved.

I laid out to the team my view of how the project should work:

• We need to think of this as a pilot project. If it works well, there will be others like it - just not back-to-back.
• Scope needs to be tightly controlled; we shouldn't try to address more than about 25 technical issues.
• I'm not going to do the writing. The subject-matter experts will do that, because they're the ones who know the material.
• Nobody will be asked to document more than three technical issues.
• Nobody will be asked to document more than one thing in any work week.
• We'll meet for half an hour, once a week. Meetings start and end on time.
• I don't want the project to run past the end of January.
  

People seemed relieved that I put so much emphasis on keeping the project from becoming a huge time-suck. Hey, we're all busy, and if we don't respect each others' schedules, we'll end up not respecting each other. We can't afford that.

At last week's meeting, I asked project team members what kinds of things they thought it would be important to document. The consensus was that we have lots of information about how to do things, but virtually no guidance on how to choose the right thing to do. We needed to capture the sequence of questions and decisions that allow a technical specialist to solve a customer's problem quickly.

I know the name for that: Troubleshooting. It's the part that gets left out of most documentation, because it's hard.

Somebody used the phrase "decision tree", and someone else mentioned that some people have flowcharts that they stick on the wall by the phone. I don't know about you, but I like flowcharts. It's often easier to diagram a sequence of decisions than to describe it in sentences.

I asked the team: Would flowcharts be a better way to capture this information than writing it out?
The consensus was that yes, flowcharts would be the best way to represent the information.
Does everyone have access to a tool that you can use to make flowcharts?
Yes, we've got Visio.
Is everyone comfortable creating flowcharts?
Yes.
That was last week's big "Aha!" - I hope it was as exhilarating for everyone else as it was for me.

Well, all righty then. We're off in a completely unanticipated direction, but that is OK. This can only work as a collaborative project, and the collaboration goes away the instant someone starts telling everyone else how they ought to do it. The wisdom of the crowd says that the way to capture the really valuable product knowledge is to make troubleshooting flowcharts. The VP of Mumble was surprised when I told him about this, but after he had some time to think about it, he agreed that we're going in the right direction.

I asked people to nominate three technical issues that need to be documented - they might be things that come up a lot, or that are very difficult to explain to new people, or that hardly anyone knows how to handle. We used a document in Clearspace (the collaboration tool available to everyone in the company) to capture the technical issues to be documented.

This morning we had a list of 26 suggestions. This afternoon we met to talk about them. We started by categorizing them, and people sometimes popped off the questions that customers would ask - in layman's language - that pointed to the topic under discussion. One of the managers said that we need to include the customers' questions in each topic, and we realized that we needed to take that thought a step further: Customers' questions, in layman's language, need to be our starting-points. When our people field the phone calls, they need to be able to look up a customer's question and link to the right troubleshooting topic.
That was this week's big "Aha!"

It's becoming a very exciting project. Not only do I have the rare privilege of watching a bunch of very smart people as they discover how information works, I get to learn from them and with them!

The Wisdom of the Crowd: Prologue

A few months back, I hired on at BlobCo. I knew immediately that I was in for a wild ride, because so many people expressed so much delight that I had signed on. (This would relate to biting off more than you can chew.) If you're a technical writer and everybody's glad to see you before they even know about your chocolate chip cookies, it's a bad sign. But now I've been there long enough that people know about the cookies. Long enough to have delivered my first big project, too; and now, long enough that people are starting to ask about other things they imagine I might do.

A couple weeks ago, the VP of Mumble came to me with a new request: BlobCo has a great team of technical people working with our customers, keeping the customers' websites and software working right. But it takes months to learn the ins and outs of figuring out what's going on when a customer's site starts misbehaving, and there's been enough turnover that the VP was very concerned about the loss of brainpower. He asked me to start a project to capture all that valuable information before it walked out the door. I told him he'd have to negotiate with my VP, but I'd say yes if my boss said yes.

The boss was sitting a couple cubicles over, so I hollered his name. "Yes?" he answered. Talk about your comedy set-up - I couldn't ask for better. "Well, there you go. That sounded like Yes to me."

I did actually give the boss a run-down on the situation. He was concerned about how much of my time it would take, so I told him how I planned to work it in:
I'm not going to do the writing.
The people who know the material will do the writing.
I'll manage the project, help them as needed, and let them know what fabulous people they are. I'll figure out how to stitch it all together and make it easy to find and to use.
But I'm not going to write the darn thing.

The boss said yes for real, once he understood the problem and the approach I planned to take in solving it. I went back to the VP of Mumble to talk through the strategy and agree on a list of the people who should be involved.

I'm not going to write this, I told him. I'll need your help no matter how we do this project, and here's what I think will allow me to keep it manageable:

• Let's have the experts each write the bits they know best.
• Each participant should nominate three things to include in the project.
• Everyone's very busy, so let's not ask them to do a lot in any given week.
• Let's not tackle everything people know how to troubleshoot - just the really hot items.
• Let's not ask anyone to write more than three short pieces.
• Let's hold the project to two months.

The VP of Mumble seemed very happy with all this. We called a meeting to kick off the project.

I know that asking technical staff to write stuff is like pulling teeth, so I used the same trick that the dentist used when I was a little kid: Toys. At the kick-off meeting, I slammed through my talking points, asked for questions (there weren't any), and then emptied a shopping bag full of toys on the conference table. Everybody had been silent through the meeting, but the toys broke the ice. People started asking good questions, cautiously voicing approval for the idea of the project and exploring the "how".

Rubber duckies, Gumby figurines, prismatic "robot glasses", wind-up toys...these got the conversation started. I'm going to need to do more than just hand out toys, though, because I have no formal authority. These people are my peers. I can't compel their participation. I must earn that, along with their respect. One of my top priorities will be to make sure that all the project participants get full credit for their expertise - because that's what keeps BlobCo successful.

Over the years, I have learned that when I don't have prior experience to guide me, the best thing I can do is tell the truth about that. So I've let everyone know that I haven't done a project like this before. (Now I can go ahead and freak out - people will understand.) But I have a plan; so we're further along on this than BlobCo has ever gotten before.

We're only a few days into the project, so I don't yet know how it's going to turn out. Stay tuned!

Table manners and project management

Have you ever bitten off more than you could chew? That was my parents’ favorite metaphor for taking on a bigger task than you’d be able to finish.

When I was about ten years old, I learned what that meant – the hard way. My little brother and I were misbehaving at the dinner table, walking the line between what would earn us a scowl and what would earn us a beating. We had made up a game: Demonstrate what not to do at table. I decided I could win the game by taking a gigantic bite. I put half a slice of bread in my mouth all at once. My father glared down the table at me. “THAT was a piggish bite,” he said.

I was unable to answer. My mouth was so full, I could not bring my jaws together without having food come out of my mouth; and if that happened, I’d get the beating of my life.

I’d bitten off more than I could chew.

I knew my father would not let me excuse myself to go spit it out. I had to swallow it somehow.
What was I going to do?

• I did not want a beating, so food must not come out of my mouth.
• Food must not choke me to death.
• The solution had to be implemented before bed time.

Those were the requirements, in order of priority.

I found I could work my jaws a little bit. Carefully, I began to chew. I swallowed a tiny bit. Chewing got easier. I swallowed a little more. Finally I was able to get through the entire wad of bread.

Since then I’ve made a habit of taking small bites when I eat. I still sometimes realize I've bitten off more than I can chew at work, though. Many of us do. Business realities mean there's often more work than people to do it. Partly this is my own reality; I choose to work for organizations that fit a certain profile, and the day I sign on, I've bitten off more than I can chew. I know this about myself. It's become a repeatable process for me:

1. Realize I’m in trouble. (Can't chew!)
   
2. Identify and prioritize the requirements for a good outcome. (How am I going to get through this?)
   
3. Identify the actions that will fulfill the requirements. (Maybe I can chew a little.)
   
4. Work through the list of priorities in order. (OK, this is working.)
   
5. Deliver what I’ve got when the deadline arrives. (Done!)
   

The solution doesn’t have to be perfect; it just has to meet the requirements that everyone agrees are the most important. I can do that every time. The key is to follow those five simple steps. I allow myself that moment of panic in the first step, and then get to work solving the problem.

Seven Habits of Highly Defective Technical Writers

If you want to be a Highly Defective Technical Writer, you need to learn industry worst practices. Here are seven to get you started.

1. People who read help are stupid. People who write help are smart. Don't ever forget that, and don't ever let your readers forget it.
   
   
2. Complexity of grammatical construction correlates in a positive manner with the perception of intelligence; thus it is advisable under all circumstances to endeavor to utilize sentence structures and locutions commensurate with the level of one's own education.
   
   
3. It is considered presumptuous to address readers as if they were present. Passive voice is preferred.
   
   
4. When documenting software that allows you to create, change, or delete something - your contact information, for example - write a separate topic for each task. It's far too confusing to provide instructions for more than one task in a single topic, or to write steps that involve choices (such as "If you need to add a new telephone number, click Add Number. If you need to change a number, edit it in the text box"). Remember, your readers are stupid.
   
   
5. Take every opportunity to continue selling your product. Remind users how attractive it is, how sleek its design and stylish its colors. Remind them how intuitive and easy it is to use.
   
   
6. People open the help when they are scared of making a mistake. When presenting a task, point out how easy it is. When you get to the step where people tend to go wrong, tell them it's really simple. People like to be reassured that they are smart enough to get it right. Remember, they're stupid.
   
   
7. Don't bother with teh spelling checker. It's for careless people who either can't type very well or are too ingorant to spell well. Your smarter than that.

When you've mastered these worst practices, you'll be well on the way to being a Highly Defective Technical Writer.

To blog or not to blog

A colleague remarked on Twitter that he's thought about blogging, but didn't feel that he had anything of value to say. I started thinking about why I follow him on Twitter: Because he's the sort of person I'd want to hang out with if we lived near each other - insightful, funny, and obviously passionate about his work. His tweets are always worth reading. I can learn from him, be inspired by him, and enjoy his wit.

And this man doesn't think he has anything to offer on a blog, so he hasn't been blogging.

One of the other threads that day was to do with the Dunning-Kruger Effect, which for years I'd been calling "meta-cluelessness" - the idea that some people lack the information or skill to discern that they lack information or skill.

My colleague seemed to be exhibiting the flip side of this effect: Highly capable people tend to underestimate their own skills and knowledge quite consistently, assuming that everyone knows at least as much as they do. If you've been doing a thing for a long time, and have quietly become an expert at it, you may take for granted what you know about it. You may assume that, since you've managed to learn how to knit socks, or rebuild engines, or write help that keeps customers from making tech support calls unless something actually breaks, surely everybody else in the entire world must know how by now.

But you're wrong. Lots of people don't know what you know. If you talk or write about it, some of those people will pay attention. Some of them will find your style engaging, and will want to learn from you. You'll enjoy getting to know some of them through their comments. You'll learn from some of them.

What are you waiting for? Your fans are looking for you. Start writing!