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.

Help, I can't find it in the index!

When you need information from a manual or a help system, how do you look for it? Many of us will use the index first, if there is one. Why?

A table of contents is the writer's view of the book. It describes the structure. It tells a story.

If you need to know one specific bit of information, you may not know exactly where you are in that story; and you probably don't care. You just need to know how to change the frabbetizing configuration settings on the MumbleCo unit, and you'd prefer to get it done before you stop and go outside for a smoke.

If your company has recently switched to this product from a competitor's product, you may not know that the appropriate terminology for the setting you want to change on this fine product is "frabbetizing configuration". You may still be thinking in terms of the competing unit from Behemoth Inc., which calls the equivalent setting on its machine "whatsit settings".

If the manual for your new MumbleCo unit has a good index, it doesn't matter whether you know where you are in the table of contents story, and it doesn't matter whether you're up to speed on MumbleCo terminology. You can look up the term you know - "whatsit settings" - and the index teaches you, very gently, "See frabbetizing configuration." And lo, when you look up frabbetizing configuration, there it is, with sub-entries that point you to all the things you might want to know about it.

If the author of the manual has given the index short shrift, you're on your own. Maybe you should take that break before you try to find the information you need.

Fairly often, the index does get short shrift, like all the other things at the back of the book. Making a good index is labor-intensive; there's no good way to automate it, regardless of what the makers of authoring tools would like you to believe. It takes a person asking "What is this paragraph about? What would I have been looking for if my search led me here?" Fairly often, the index entry is a phrase that does not occur in the indexed material. But the fact that it may take 6 to 8 hours per page to create the index does not mean you should skip it.

The index is a reader's random-access information discovery tool, and it is (or should be) the writer's teaching tool. With all due apologies to Adobe, try this experiment: Look for a specific bit of information, using generic terminology, in the help for an Adobe product. For example, in Illustrator, how do you move a vertex to change a shape? You'll see what happens when you overlook the teaching aspect of the index. In Adobe-land, you have to know the terminology already to find the help you need. But who needs the most help? People who have no prior experience with the product, and don't know the terminology. In all fairness, Microsoft is just as bad; I never have been able to figure out if there is a way to change rows to columns and vice-versa in Excel when I decide I've structured my spreadsheet badly. And I have never been able to make heads or tails of the bookkeeping software I bought last year, because I don't know the terminology. In each case, the index fails in its teaching function - it doesn't include plain language that refers me to the specialized term.

The lack of a well-designed index in a manual or help system makes the whole product less usable.

When you work out the schedule for writing a manual or help system, include the time to create an index. In my experience, it will take about a sixth of the total writing time; your mileage may vary. But no matter how much time it takes, do it. Your readers are counting on you.

Warnings that don't work

On my way home from the property tax office, I saw a road sign that made me think long and hard about what we writers do. It's a diamond-shaped sign, gold with a black border - the standard US format for free-form advisories. It says:
CAUTION: HILL BLOCKS VIEW

Why yes, so it does. Hills do that as you approach them; otherwise they'd be valleys or plains. I wondered, How much did we taxpayers fork over to have the highway department inform us of the obvious? But wait, there's more. The hill in question is neither the first nor the last on this road. It is, after all, a road through the Texas Hill Country.

Perhaps there is something special about this hill, then.

At this point my philosophical quest began to make headway.

What's special about this particular hill is not that it is, like most hills, opaque. The significant data are that it has two crests, and between them is a large church that's often used by civic organizations as a meeting-place. People driving out of the church's driveway are at significant risk of being hit at highway speed by their neighbors, or by the gravel trucks coming from the quarry just down the road. This information would not fit on a road sign, however; so we ended up with an advisory that states the root problem without giving us a clue about its all-too-common consequences.

Drivers cannot change the opaqueness of hills; but if we are aware that we are on a blind approach to a heavily trafficked driveway, we can exercise caution by slowing down and paying close attention to the road. Why, then, does the sign not say SLOW - TRAFFIC ENTERING HIGHWAY? For that matter, why did the highway department not lower the speed limit on that bit of road?

The sign is technically accurate. The hill does block the view. But out of all the information that drivers need about that bit of road, the author of the sign chose one of relative unimportance. The sign neither explains the hazard nor guides us to the correct action.

Road signs make Twitter look like Russian novels. They must be concise enough that a driver moving at highway speed can read, understand, and act upon them without being consciously distracted from the task of driving. Every word must be chosen with care. But this is not enough: Those carefully chosen words must express the right message. They must get to the heart of what is important about a road hazard.

We technical writers face the same challenge. Sometimes our readers need guidance to avoid hurting themselves, damaging the product, or losing data. In such cases, we need to tell them what consequence they need to avoid. It's not nearly as helpful to tell me that the machine may overheat if I operate it inside a cabinet as it would be to tell me that it may catch fire if I do that.

Sometimes our subject-matter experts do not make clear what the consequence of ill-advised action (or inaction) might be; in many cases, this is because they assume that anybody is able to understand the implications of the hazard. We need to ask them if they don't volunteer the information. "So, forgive me if this is a silly question; but what would happen if I put the machine in a cabinet and it overheated? Would it melt? Would it catch fire?"

Having elicited the information we need, we can wordsmith it into a form that will give our readers the information to prevent problems. That's the goal. That's always the goal when warning readers about anything. There's nothing so useless as warning people about things they can't change.

Hills have always blocked views and always will. But if we know about the hazards they hide, we can take steps to reduce the risk.

Recipes, assumed knowledge, and indexes as teaching tools

Consider: Recipes and cookbooks are one of the oldest forms of technical writing. They tell you how to complete specific tasks, and what results to expect. Cookbooks also have explanatory material to help you understand the techniques and terminology in the recipes, along with conceptual information - why you knead bread but handle pie crust dough as little as possible, which ingredients can be substituted for others.

When my Grandma Mulholland passed away years ago, I inherited her recipe box - and realized that we technical communicators can learn a lot from trying to follow old recipes. Grandma's fudge recipe (transcribed here exactly as my grade-school educated Grandma wrote it) provides some examples.

Quick Fudge
2 1/4 C Sugar
1/2 Cube butter
1 small can Carnation milk = 2/3 cup
Boil 5 minute stir constantly
Remove from heat, add 1 1/2 C Mineture Marsh mellow and 1 Pkg of Choc Chipps - 1 t flavoring
Beat untill all disolved. Add 1 C Nut Meats & stir them in
drop by spoonfull on Wax Paper...buttered dish - cut when cool

Grandma made a lot of assumptions about what people know and what they can buy at the grocery store. Fortunately I could remember what was available in the average grocery store in a smallish city in Indiana back when the world was a large place and other parts of it were far, far away, so I was able to figure out what this all meant.

The 2 1/4 C sugar was pretty straightforward; it meant granulated white cane sugar, the default choice of sweetener in the midwestern USA during the middle of the 20th century. If Grandma had meant brown cane sugar, she would have said so - and she never encountered any other kinds of sugar.

Half a cube of butter? A bit tougher. Looking at the quantities of the other ingredients, I decided that was half a stick: 2 ounces, or 4 tablespoons.

Carnation milk would be evaporated milk. Two kinds of milk came in cans when my Grandma started using this recipe: Carnation milk, which was evaporated; and Eagle Brand milk, which was condensed and sweetened. I remain grateful that Grandma saw fit to note that a small can is 2/3 cup.

Miniature marshmallows are still with us, so that was no problem.

I had to think hard about the chocolate chips. These days I buy them in 24-oz bags, but they weren't available in such large packages when Grandma was still making fudge. I racked my brain. Grandma was not one for buying large quantities of stuff and then keeping it around. Ah - so it would be the smallest size, otherwise she would have said what size bag. So it's six ounces of chocolate chips. I used six one-ounce squares of Baker's chocolate instead, and the fudge came out right.

That brings us to "1 t flavoring" - a teaspoon of...what? Well, vanilla, again because that was the default in mid-20th century cooking in the midwestern USA. You put it in most sweets, and it was nearly mandatory in anything with chocolate.

And that cup of nutmeats - that had to be chopped walnuts. If you climbed in a time machine and went to a Kroger's or A&P in Indiana circa 1965, right beside the six-ounce bags of chocolate chips, you'd find bags of chopped walnuts. There would probably be slivered almonds as well, but they were for exotic stuff like green bean casserole. You'd never have put them in fudge. And the pecans were out of the question. Only a Southerner would put them in fudge.

So here I sit, nibbling on fudge that tastes exactly like the stuff that Grandma made every Christmas, and reflecting on how much I had to know to make that recipe turn out right.

It's making me think about what a hard time I've had learning some popular software tools, such as Adobe Illustrator and Microsoft Excel - in each case, there was a body of assumed knowledge that I did not have. In each case I had trouble using the help because I did not know the names of things. And in each case the help index failed in its teaching function - I could not look up familiar terms and get "See" or "See also" entries that pointed me to the help I needed. Sometimes I muddled through until I stumbled upon something that worked, sometimes I asked a friend, sometimes I gave up.
Well, fudge.

The service manuals of yore

When I gave up my workbench and oscilloscope in the R&D lab for a desk in Field Service Technical Publications, I learned to structure product service manuals in this way:

• Introduction
• Theory of operation
• Controls
• Removal/replacement/adjustment procedures
• Field-replaceable units
• Installation procedures
• Fault isolation tables
• Technical specifications

This was the One True Structure, handed down from on high. (I think it was probably carved on stone tablets, but since I didn't work at headquarters, I never saw them.) Nobody questioned The Structure. Nobody asked whether it made information easy to find.

In truth, it was worse than that. "User-friendly" was a derisive epithet, uttered with a sneer. Were our field service engineers such a bunch of babies that they couldn't handle a proper 350-page service manual?

My goodness, how the profession has evolved since then. How our philosophy has evolved!

Sometimes I wish I could go back and rewrite my first manual using what I know now, and lead my benighted colleagues into the light. Great material, bad sequencing, I would tell them. Shorten the introduction to one page maximum. If our field engineers missed training on this product, they still know a printer when they see one, so just hit the high points. They're our engineers; you don't have to sell it to them. Installation procedures next. Then controls. Testing and fault isolation. Removal/replacement/adjustment procedures; roll the information about field-replaceable units into that chapter. Performance verification and technical specs last.

The clouds would part and angels would sing when the field engineers found that they didn't need to skip all over the book to find the bits they needed. O, for a time machine to let me go back and light the way.

Bah.
Our whole profession marched boldly forward, through the dark times and into the light. We thought things through. We learned from each other and taught each other. Those ponderous 300-page manuals that seem to have neither rhyme nor reason are a thing of the past. We learned a new word: usability.

We technical communicators grade our work now on the percentage of help desk calls that are due to actual product malfunctions or defects rather than issues that our customers can resolve on their own. It's still important that the relevant information be documented, but now we know that information is only useful if you can FIND it.

We got there. No time machine required; just the magical alchemy wrought by time itself - time, and passion for communicating technical information clearly.