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.

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.

New Year's Resolutions

...need project management.

(Full disclosure: This post is not about technical communication.)

Our resolutions tend to shape up as long wish lists that detail our individual perceptions of fabulousness and how we deviate from that ideal - rather like the grab bag of cool features that everyone wants to add to a product in its next release. And like that long feature list, our lists of resolutions contain many items that will be dropped, and a couple keepers.

In a product development project, it's OK for features to fall off the must-do list. But when that happens with one of our New Year's resolutions, we feel guilty about it. To make up for it, we make more unrealistic resolutions, fail to keep them, and feel guiltier: Jeez, this same thing happened *last* year! I can't even keep a crappy resolution! I'm a failure because I didn't pay off all my debt, lose 25 pounds, go to the gym three times a week, quit smoking, and write to my mom once a week! I'm a failure! I have to try harder! I know, I'll do charity work and give blood!

OK, STOP IT RIGHT NOW.

In product development, a successful product release usually has just one or two "wow features", along with some minor changes. Try applying this idea to your resolutions.

What's your wow feature for 2010? Pick ONE - just one. Are you going to quit smoking? If you keep that resolution, nothing else matters. The same is true for paying off all your debt, losing 10 pounds or more, or adopting a regular schedule of exercise. Decide to do any one of those things, and if you want it to happen, you'll be able to do it - and make a huge improvement in your life. Try to do more than one of them, and you're likely to fail. So pick one.

If you feel that you should have more than one resolution, pick your "wow resolution" and then make a handful of BS ones that you'll be able to keep without much effort:
I resolve that I will not let my household run out of coffee or beer in 2010.
I resolve that I will put a new roll of toilet paper on the roller if I use the last of the old roll.
I resolve that I will get my car's oil changed in accordance with the manufacturer's recommendations.
I resolve that I will always tip at least 20% unless I receive really craptacular service, in which case I'll leave a note explaining why I felt the service was bad.
I resolve that I will put paper in the printer instead of waiting for someone else to do it.

Not all product releases have wow features. Some are just bug-fix releases, which are what they sound like. You could decide that 2010 is a bug-fix year, and not have a wow resolution. How about just a handful of bug-fix resolutions, aka BS resolutions that will be easy to keep?

After 2009, that's an attractive idea, don't you think?

If you haven't anything good to say...

If you woke up one day, prepared yourself to face the world, and realized, "My goodness. I have nothing good to say," or worse, "My goodness, I have nothing at all to say," would you say it anyway? Or would you let your blog get one day more stale?

And if that day stretched to a week, or a month, and you found yourself thinking, "My goodness. I still have nothing (good) to say," would you grow alarmed? Would you fault yourself for being lazy and self-indulgent, and firmly compel yourself to manufacture something you could post? Or would you keep silence out of concern that every time you tried to write, you found yourself wasting the time of your readers?

We all know that if you start a blog, you should treat it as a commitment as firm as any job. You should keep it fresh, expound upon matters within your realm of expertise, keep the opinions and advice coming. Stay positive. Build that Brand You. Market yourself nonstop.

But what happens if you DO hit a wall?
You go crunch, silently.
My goodness. I have nothing to say.

Reclaiming the boxes

A good friend just called me out - and properly so - for neglecting my audience (well, he said my blog) for so long.
I'm sorry.
Forgive me, readers, for I have sinned. I did not meet your expectation that I'd say something from time to time. I committed the writing sin of letting the material get stale. I demonstrated poor work habits by failing to treat this blog as work. Mea culpa. This is one time when it would have served me better to do a very 20th century thing: compartmentalize all the messy bits of my life.

Remember compartmentalization? It was the notion that you could chop up your life into chunks and put aside the bits you didn't want to think about at any given time. Remember what a bad reputation it had? Such an unhealthy thing to do - denying parts of your experience, your personal narrative. We're so much more emotionally healthy if we throw away all those little boxes that we use to compartmentalize our lives. And a lot of people did that.

You can identify the people who threw away the boxes, and don't approve of compartmentalization. The extreme cases are the ones at the next table over in your favorite restaurant, Having Issues (maybe even breaking up) in public; the ones in the office who are always on the phone, talking to friends about other friends, doing that thing we call "homing from work".

My office is in my house now. I was once skilled at compartmentalizing the parts of my life that don't need to come to work with me, but changing the way I work is changing the way I handle the rest of my life, too. I think I've still got the mental boxes for compartmentalizing my life; they've just gotten a bit muddled up. I work at home; does this go in the work box or the home box? It's easy to get sloppy.

Some things happened recently in my personal life, and rather than risk having them spill into the professional side of my life, I stopped blogging for a while, on the theory that it's just my blog and I can take a break if I want to. That wasn't a good way to deal with things. Old-school compartmentalizing would have served me better.

You'd think that after living through a couple decades of radical changes in people's assumptions about how we work and why we work and what we do for a living, I'd be better at adapting - but this isn't a matter of learning anything new; it's a matter of going back to what was considered good business etiquette a generation ago. Clothing styles from the '70s are back; maybe it's time to give retro work habits another look, too.

Tina the Technical Writer doesn't work here

If you're a technical writer, you may have had this experience:
The new guy on the product support help desk walks in, holding the system administrator's guide that you designed, researched, wrote, and illustrated. He scans your cubicle, looking for signs of - heaven only knows what, but clearly it's not there.

Help desk guy: "Hey, I just started here and they handed me this manual. It's great! Who wrote it?"
You: "Um...I wrote it. I'm the technical writer."
Help desk guy (gawking): "YOU wrote it??"
You: "Yes. That's my job. I write the manuals. I write the help, too."
Help desk guy: "Who helped you with it?"
You: "Each of the developers answered my questions about the features they own, and they each reviewed the topics where their features are discussed."
Help desk guy (floundering): "But...I mean...how did you know what to write?"
You: "I started with the product requirement documents and the feature design documents, and I spent a lot of time playing with the product as soon as it was stable enough for me to poke around at it."
Help desk guy: "You actually use the product?"
You: "Sure. There's really no other way to get familiar with it, and I have to understand it myself before I can help other people understand it."
At this point the help desk guy generally wanders off to recover from having his world rocked.

If you've ever had that conversation with the disbelieving help desk guy, you know the source of his disbelief and your frustration: Enough people have encountered non-stellar tech writers that stereotypes exist. You can't change that. Neither can I. The only thing we can do is choose not to conform to the stereotypes.

So forget Tina the Technical Writer, the character in Dilbert. She's a cartoon character. Roll up your sleeves and get into the technical details of the thing you need to explain to your customers. Tell your developers when you spot things that may cause problems for customers - "Can you build some validation into this field? Right now, this form lets me build a test condition that's nonsense." Focus on what you do best and let the stereotypes take care of themselves. It doesn't take long for people to realize that whatever they expected, in you they've got a person who readily grasps technical concepts, is passionate about communicating useful information to people who need it, and visibly contributes to the organization's success.

What do you want?

A friend of mine - I wouldn't say "an old friend"; but definitely a friend of long standing - emailed me this evening with about fifteen great ideas for things to blog about. The one that caught my attention was his suggestion to shine some light on the sleuthing that technical writers have to do to get a project done.

Most technical communicators have stories about having to get product requirements and functional specifications by hook or by crook. Most of us have stories about trying to get product feature information from the engineering/development team. But the detective work needs to start a long time before then. We need to be mindful of this universal truth:
People ask for what they think they can get - not what they really need or want.

Not too long ago, an engineer came to me in a tizzy - a major customer had asked for a special widgetizing device. The engineer had designed it, developed a test plan, and determined what certifications the new MumbleCo Widgetizer would need. Then - oh, my goodness! - he realized that his project would go nowhere without product documentation.

My engineer friend knew I wrote manuals, so he asked me to write a manual for it. He knew he could get that.

I looked at the Widgetizer. I asked some questions.
What problem does it solve?
What do you use it with?
How do you connect it?
Does it matter which of these connectors you use?
Does it require any new software? Does it have any smarts?

It turned out the Widgetizer was a very simple device designed to do a single thing in a single context. It didn't need software. Plug it in and watch it go.

OK, I said, so about this hypothetical Widgetizer manual: What problem do we need to solve?

We need to tell the customer how to install and use it, said the engineer. He did not say we needed to explain how it works. I love working with this guy; in some crucial ways, he *gets it*. But I'm still trying to coax him into asking for what he needs instead of what he thinks he can get.

So: The Widgetizer has three connectors, two of which are interchangeable, and it lets you do one thing once it's installed.

After an hour or so of discussion, we agreed on the product documentation for the Widgetizer: a label on the connector panel to identify each connection, and a single-sheet document that included text and pictures to guide customers in setting up the Widgetizer and using it. When I presented the finished material for review, my engineer friend agreed that the Widgetizer sheet covered everything a customer would ever need to know in order to use the product successfully. We decided to have it printed commercially and folded up in the box with the Widgetizer. We all lived happily ever after.

I never did write a manual for the Widgetizer. Sometimes I wonder, though, whether there are any customers longing for a 20-page Widgetizer manual.
If so, I hope they'll ask for what they want rather than what they think they can get.