Out-of-the-box dox

Mockingbirds and Robins: How We Face New Ideas

2012-01-15T13:15:00.000-06:00

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

2011-09-05T00:07:00.008-05:00

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

2011-04-29T19:29:00.003-05:00

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

2011-04-01T22:15:00.005-05:00

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

2011-01-28T12:07:00.004-06:00

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

2011-01-08T13:33:00.003-06:00

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

2010-12-10T22:25:00.003-06:00

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

2010-12-05T21:24:00.007-06:00

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

2010-09-19T22:12:00.004-05:00

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:

Realize I’m in trouble. (Can't chew!)
Identify and prioritize the requirements for a good outcome. (How am I going to get through this?)
Identify the actions that will fulfill the requirements. (Maybe I can chew a little.)
Work through the list of priorities in order. (OK, this is working.)
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

2010-07-18T17:38:00.004-05:00

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

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.
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.
It is considered presumptuous to address readers as if they were present. Passive voice is preferred.
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.
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.
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.
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

2010-07-08T22:14:00.004-05:00

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!

What happens next?

2010-02-08T18:03:00.005-06:00

I am a busybody. I am a Nosey Parker. I can’t help it.
No, I am not interested in who goes to lunch with whom, or who takes advantage of the privacy afforded by the server room. I’m intensely interested in what happens next.

When you finish doing your little piece of the great process of keeping your organization going, who receives your work when you hand it off? What happens next?

When I went to work at a company I'll call MumbleCo, I found that none of the writers knew how their work got from their desks to our customers. Not even the manager knew the release process.

Any time you don’t know what happens next after you do your part of a business process, you’re automatically looking at a broken process. In an organization, the thing you deliver is the input to the next person’s part of the process, and as any programmer will tell you, GIGO – garbage in, garbage out. If you don’t know the next person’s part, how do you know you’re not providing garbage input?

The cure for a broken process may be as simple as finding the person who handles the next part and having a conversation about how the process works now, how it would work in the ideal case, and what causes problems.

At MumbleCo, all the manager could tell me about the release process was “We hand it off to someone in operations.” I went to the operations group and introduced myself to the manufacturing engineers, logistics planners, and the change control team, and asked questions about how they worked. How could we writers help to keep them from having to do extra work? They offered very specific observations:

Nobody used the right process for getting part numbers.
It was hard to draw up the release paperwork for a manual because writers didn't provide enough information in their emails and the file names were all over the map; the change control team usually had to open the file to find out the manual title and the product line to which it belonged.
Sometimes we sent them files that they couldn’t even open.

I took this back to my manager. She recognized the value of aligning what we did with what Operations needed, and put me in charge of designing and implementing a release readiness process to include assigning document numbers, setting a file naming convention, and checking finished manuals against a production readiness checklist. The other writers complained about the new process – “Why can’t I just give it the next part number? Why should I have to let you check it? I'm a senior writer! We never had to do this before!” – but the operations team knew who to contact if there were problems, and document release went from a two-week process to a two-day process.

This change didn’t require a decision at the director level, a six-month study, or a task force. It took one writer, in a non-supervisory role, walking to the other side of the building and having a series of conversations with the people whose days she could make or ruin simply by how she did her job.

Do you participate in a broken process? When you finish your piece, what happens next? If you don’t know, go find out. Fixing a broken process starts with a conversation.

How to develop X-ray vision

2010-02-01T15:31:00.005-06:00

Standard prerequisites for superheroes include being faster than a speeding bullet, being able to leap over tall buildings at a single bound, and being more powerful than a speeding locomotive. We’ve talked about how technical writers can meet all those qualifications. But real superheroes have X-ray vision, too.

Have you ever looked at a web site, picked up a brochure, or read a manual – and spotted a really dumb mistake? Quick show of hands - who hasn’t? I didn’t expect to see any hands up, and you didn’t disappoint me. Wouldn't you like to hang this AWARD OF EXCELLANCE in the entryway to your business?

After you look at the material long enough, you lose the ability to see your own mistakes. We know this. Quality checks help us see things we would miss otherwise, so that we never publish material that embarrasses the organization.

Things to check include:

Formatting – if you control the formatting in the final deliverable, include separate checks for every aspect of this: font usage, text size and spacing, placement of graphics, headers and footers in print-oriented material…you can probably come up with a full page of format checks.
Spelling, grammar, and punctuation – did you run a spelling check? Has someone read it through for grammar and punctuation? We are better at grammar checking than automated grammar checkers are, especially if the material is specialized technical information.
Table of contents – is it complete and accurate? Was it generated after everything else was done?
Index or search – you have this, don’t you?
Parallelism in headings – If one topic is called “Creating accounts”, don’t call the next one “How to delete accounts.” Again, we know this. But if you collaborate with others on a work, or if you start a new topic without reviewing other topic headings, it’s easy to end up with headings that don’t follow consistent grammatical structures.
Consistent grammatical structure in the text – for example, “To [start a task], click [button or link name].” If your work gets translated, this cuts the cost.
Conformance to your organization’s style guide – you have one, don’t you? If not, start one right now. Start with an item about using consistent grammatical structures.
Conformance to your organization’s identity standards – check for proper use and placement of the logo, correct color formulations, and whatnot.
Links and email addresses – don’t trust them; test them.
Conformance to file naming conventions – you have those, don’t you? Consistent file naming helps you find things later on, particularly if you use a version control system. Make file naming a part of your quality checklist so you can enforce it.

If you check your work against your quality checklist before you publish it, you’ll have the X-ray vision to catch things nobody else has spotted in earlier checks, and you’ll always publish material that shows your organization in its best light.

A tip of the hat to Thomas Moore of StorSpeed, who shared his checklist with me ten years ago. The man’s had X-ray vision as long as I’ve known him.

Tactics for being more powerful than a speeding locomotive

2010-01-27T15:38:00.004-06:00

We’ve been talking about how to be a technical writing superhero – get the right information to the right people in the right way; be able to show your management that your project is on track. But if you’ve ever waited for a train that was late, you know that on track isn’t the same as on time.

Time management means being able to say no. Whenever someone comes running to you saying “I need your help,” it’s automatically an emergency. You’re a team player, so you may say “Sure, I can help you with that” without thinking.
Stop.
Think.
That emergency has the momentum of a speeding locomotive, and it will derail you if you’re not strong enough to stand against it. Is it really is more important and urgent than your project? Are you really the only one who can do it? Estimate what it will do to your schedule. If you aren’t completely in charge of your assignment list, ask your manager to make the decision. You don’t take the blame for schedule changes when your boss is in charge of signaling and switching the tracks. If you work on the emergency project, notify the rest of the project team – don’t wait for your boss to do it.

Speaking of locomotives, training can also derail you. My own time management epiphany came when I went to the office to put in a few hours after a full-day seminar at a nearby hotel. Then it hit me: “I just piddled away an entire DAY on a time management seminar that my boss sent me to, and my deadline’s Friday.” I think I bent the needle on my irony-meter. My boss (evil man!) smiled knowingly when I confronted him the next day and asked him never again to schedule me for training near a deadline.

Less obvious but more common is the failure to prioritize tasks. How many times have you worked on a diagram, tweaking and tuning and rearranging until you realize you’ve spent half a day on a picture that only reinforces existing text? Was that critical to the project? Hardly.

Remember the project spreadsheet I described in the last post? It prevents train wrecks. With two more columns, it becomes the train schedule. On your master list of information changes, add a column for prioritizing each item and a column showing anything that blocks you from getting it done. (Yes, it’s getting to be a great big spreadsheet with lots of columns. Hide the ones you’re not using at any given time.) Now you’ve got a system. Whatever you’re working on, you should be done with all the higher-priority items except those on which you’re blocked.

To review: your spreadsheet includes a master list of changes, with separate tabs to show the changes to each of your deliverables. Columns on these tabs are:

Information change
Work required
Priority
Blockers
Subject matter expert
Questions
Date completed
Date sent to review
Date corrections received

With your spreadsheet superpowers, you’ll be able to stand firm against other people’s speeding locomotives and avoid derailing yourself.

Tactics for leaping over tall buildings

2010-01-21T15:39:00.007-06:00

We've talked about how you, the superhero technical writer, can be faster than a speeding bullet through effective audience analysis and information design. “Sure you’re faster than a speeding bullet,” says the boss, “but what else can you do?” It’s time to leap over a tall building or two.

Leaping over tall buildings would be easier if we had a Shrink-o-Matic ray that scaled the buildings down to the size of things made with Lego® blocks. So let's build one, and let your boss keep thinking of you as a superhero. Key components of the Shrink-o-Matic ray gun: Project management and technical review management.

How do you keep track of project requirements? How do you stay informed of all the new features under development? How do you determine what parts of the documentation are affected by each change or new feature? How do you ensure the material is updated?

Start with a project plan that shows the reason for the project (such as a new software release), the schedule, your subject-matter experts and other project stakeholders, your deliverables and the scope of changes to them, your assumptions, and possible risks. Distribute this to all the project stakeholders. Publish it on your intranet. Update it weekly.

When your first draft of the project plan is done, start building your project tracking spreadsheet. Include each new or modified product feature on its own row. Identify which subject-matter expert owns each feature and which of your deliverables will cover it.

Create additional tabs in the spreadsheet file, one for each of your deliverables. For each one, pop in the topic outline that you created in the design phase – one row per topic. Start with these columns:

Topic - this is the first or second column, depending on whether you want to show the topics by chapter or help book.
Work required – specifies whether the topic is to be created, updated, or left alone.
Subject-matter expert – who owns this information?
Questions – anything you need the subject-matter expert to answer; any unresolved issues.
Blockers – anything outside of your control that's keeping you from finishing the topic.
Updated – check off each topic as you finish it.

As the project moves along, you can use the Questions column to create lists of questions for each subject-matter expert, so you can schedule short appointments with each of them to get the information you need.

When you encounter a blocker, bring it up in the next project meeting if it's not a well-known situation already - and mention it even if it is well-known. For example, "I still have a couple topics on feature X, which hasn't been coded yet, so I'm dealing with other features that are further along."

Now here’s the power-booster for your Shrink-o-Matic ray. For each deliverable, add two more tabs:

To review - the date when you hand the topic to the subject-matter expert who owns it.
Corrections received - the date that you get the topic back with corrections.

If you send out a whole manual to a whole team for review, they’ll hate you – and they won’t review it thoroughly. If you send topics out one at a time, as you complete them, and send each topic only to the developer who knows it best, you may get corrections back the same day. What’s more, there won’t be a big review backlog near the end of the project. Your organization may not be agile, but there’s no reason you can’t be. Working this way shrinks those tall buildings to something you can leap over, with your superhero cape billowing behind you quite convincingly.

A tip of the hat goes to John Hedtke, who introduced me to a stripped-down version of project management by spreadsheet several years ago.

Tactics for being faster than a speeding bullet

2010-01-19T13:51:00.002-06:00

In my last post, I described a situation in which one technical writer (yours truly) delivered a huge volume of customer information every four months and made it look easy. What did it take to be a superhero?

Audience analysis
Information design
Project management
Review management
Time management
Quality checks

Let’s talk about the first two tactical considerations – audience analysis and design.

Who are your customers?
What do they need to know?
What do they already know?
Do they know more than you do?
How can you make them happier with your organization than they are now?
Who are your competitors and what can you learn from them?
You can’t make rational choices about how to select, organize, and present information unless you know who will receive it and how they will use it. This is bedrock basic technical writing theory, and some writers still ignore it. Don’t. If you skip the audience analysis, you’ll do extra work and you won’t have time to outrun that speeding bullet. You’ll also fail to deliver what your customers need. They’ll call technical support to ask questions that start with “How do I…?” If you let that happen, the aforementioned speeding bullet will come from the help desk.

Information design flows naturally from knowing your audiences and understanding what they need. If you write about a product that people use in different ways depending on their roles, you know to segment the information based on roles. The person checking their own work into and out of a repository doesn’t need to know how to do database administration. Chronology may also provide a good criterion for sorting information: for hardware, you’ll often need an installation guide. Anything that happens after it’s installed can be documented somewhere else. How do you decide where? Try an outline. It’s old-fashioned but it works. Start by throwing everything you can think of into one outline; you can decide later how finely you need to slice and dice it up into manuals, tip sheets, tutorials, and whatnot.

When you start with an outline, things are packaged into tidy little headings. It’s orderly, with clear boundaries, almost like a coloring book. Why not keep it that way? Think and write in topics rather than sections. What’s the difference? Sections can ramble and sprawl sometimes, because they may start with one topic and digress to another. A topic is everything you need to know in one context about one thing – for example, how to change your password. It stays focused, and you only write it once. When it’s time to update the information, you can quickly identify which topics are affected, and leave the rest alone. When you don’t have to go through every word, updates are a lot faster – maybe even faster than a speeding bullet.

Faster than a speeding bullet

2010-01-15T17:05:00.001-06:00

Two products that work together, customer information delivered on a CD as printable manuals and HTML help branded for the company and unbranded for its OEM partners, a four-month software development cycle, one technical writer.

One technical writer who does not pull late-nighters or work from home on weekends. One technical writer who meets deadlines and wins awards for the material.

How does that work?

Pretty well. Thanks for asking.
It’s all about strategy and tactics. The strategy is pretty simple: Do only the things that move you forward, but do whatever it takes to keep moving. The tactics are familiar, in principle at least, to most technical writers:

Audience analysis – who are your customers? What do they need to know? How do they find out now, and how would they like to find out?
Design from meta to micro – what are your largest units of documentation, and how do you decide what belongs in each one? What are your smallest units? How do you assemble the small units into the big units? How do you integrate new pieces of information? How do you make sure you'll never be caught flat-footed by a new requirement, such as translation?
Project management – how do you keep track of all the project requirements? How do you ensure that you are aware of all the new features under development? How do you determine what parts of the documentation are affected by each change or new feature? How do you ensure all the material is updated?
Time management – how do you make sure the important things get done and the project stays on schedule?
Technical review management – how do you persuade your technical experts to give up some of their precious time to check your work? How do you ensure they’ll be willing to do it again?
Quality checks – how do you make sure that you publish material that won’t embarrass the organization?

Tune in next week for some answers.

Check your work

2010-01-08T11:15:00.004-06:00

Think back to grade school. Think back to math tests. Remember what the teacher said at the start of every exam? "Check your work." The teacher knew that although you may know the heck out of long division or fractions, it's still easy to make really dumb mistakes - and the dumber the mistake, the easier it is to make. Worse, the smarter students are more confident of their ability to do error-free work, so they're less likely to catch their own really dumb mistakes. Sad but true: In my fifth-grade class, the class brain misspelled his own name on an exam. The teacher docked him three points for it, so he scored 97%.

We don't magically get over this when we finish school. What was true in grade school is still true, and it's more complex in the workplace because we aren't just answerable to ourselves; we rely on other people to do their work accurately, too.

You should be able to trust your teammates, but we all make mistakes. You won't make any friends by compulsively checking everyone else's work - and you'll run out of time to do your own work if you try - but if your organization doesn't already have a formal mechanism in place, you can set an example by asking your teammates to check your own work. "Do you mind checking this section for accuracy? If you like, I'll check whatever you have ready while you're looking at my material."

A couple things seem to cause a lot of trouble in technical writing and marketing collateral: company URLs and email addresses. I have seen far too many tech-savvy businesses (including IT service providers and multinational telecoms companies) publish contact email addresses that did not exist on their mail servers. They instructed their customers to contact them via email addresses that returned error messages. How smart would that make your company look? Although the warranty card may have always included the email address support@yourcompany.com and the URL www.yourcompany.com/support, that doesn't necessarily mean they work.

Take a few seconds to see what happens when you follow that link. Take a few seconds to send a test message to that email address, with an explanation and request for reply. Check your work.

New Year's Resolutions

2009-12-27T21:32:00.005-06:00

...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?

A glass half-full of new wine

2009-10-12T20:13:00.003-05:00

A while back, I encountered a former business associate at a coffee shop and explained to her that I was embarking upon a career change. She told me I was overdue - on average, she said, people change careers every seven years.

Seven years - is that all? It's probably going to take me seven years to stop viewing the world through technical-writer-colored glasses. Navigating the intricacies of the red tape surrounding the training program I'm in, I've been documenting and reporting what it's taken to get things done. Looking through my new Cisco networking book today, my mental editor had her blue pencil out. Even so, I was a lot more mentally engaged with the idea of scoring a free motherboard. This tells me my mind-set is starting to move.

I'm still getting inquiries about my technical writing services from potential clients, some of whom seem intrigued at the idea of a technical writer with IT chops. For all I know, this may be less a career change than a specialization. But I'm excited about the possibility of doing something totally other than writing for a living.

The future looks frightening when you look forward and see only a wall; but when you look forward and see a multitude of paths, it's hard to be anything but optimistic.

Waking up is hard to do

2009-08-08T13:36:00.003-05:00

Change is hard.
Challenging your own assumptions is hard.
Waking up and realizing that you need to change is enough to send a lot of people back to bed. It's so hard that many people, confronted by the need to change, don't change. So people stay in relationships that no longer work. So people become old and bitter from decades of doing work they hate. So people die from things they choose not to change - smoking, drinking, other drugs. At some point, the cost of changing becomes smaller than the cost of not changing. If you are fortunate, you wake up and realize that.

My mind realized a couple months ago that I had reached that tipping-point (My job is not me, May 27), but it took some time to accept it in my heart.

I love the process of learning and documenting a technical product - playing with it, asking the engineers how they intended a particular feature to be used, picking the support technicians' brains about what problems make up the bulk of customers' calls to the help desk, comparing notes with the software quality assurance people when I encounter an unexpected behavior. But I still get irritated at having to combat the common perception that "technical writer" means "non-technical person who writes about things she doesn't understand."

I love the process of working out what kinds of information people need, what audiences I must address, and how to chunk up and present the information to meet each audience's needs most effectively. I love the process of creating the process - how will we consistently meet schedules? How will we consistently produce top-quality work? How will we handle version control? How will we ensure that our processes scale as flexibly as the company's product strategy? But I still get irritated at having to combat the perception that somehow, as if by magic, all this takes care of itself for technical writing even though it does not in other areas, because after all it is only writing and anybody can write.

I love working with engineers who know they can "talk tech" to me. I don't love managers who insinuate that they can have the new intern write the manuals instead. (Bubba, I hope you're right about your intern, because I'm not going to do business with you.)

I just woke up and realized that it costs me more to keep calling myself a technical writer than it does to take advantage of the glorious opportunity this recession has handed to me. I've had to work through a lot of internal resistance to change, but I've gone back to school. I've chosen to start a new career doing the thing I had originally envisioned when I started college. I'm studying for my first round of IT certifications.

I'm sure I'll keep on doing technical writing as a sideline, just as I never completely stopped fooling around with electronics; but it's not going to be my whole life any more - and neither is my new career. I've learned the hard way about allowing my job title to trap me in a box.

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

2009-07-30T21:53:00.003-05:00

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.

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

2009-06-04T17:58:00.003-05:00

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.

My job is not me

2009-05-27T15:20:00.003-05:00

I am a technical writer.
I am a technical writer.
I am a technical writer.
That's been my mantra for many years. In the last few days I've had an experience that felt like waking up, but on a grander scale.

I'm not a technical writer.
I'm a woman with diverse interests, dreams, anxieties, strengths, weaknesses - and, oh yeah, I know how to make a living writing about high-tech gadgets. Surely I could draw a line through a different set of interests and strengths, and discover how to make a living doing something else I enjoy. But this is scary, crazy thinking. My brain freezes as soon as I realize that the logical next step is to contemplate a career change. So I stop in my tracks and meekly go back to thinking "I am a technical writer."

I'll have to change my thinking in baby steps. The first baby step is, as any good writer knows, to get rid of the passive voice. Find "I am a technical writer." Replace with "I do technical writing for a living." Ah - that creates breathing room, and the other aspects of me start reminding me that they're still here: Empty-nest mom, former Girl Scout leader, herb gardener, handweaver, swimmer, baker of uncommonly good pies. Music lover. Amateur carpenter. I don't do any of those for a living, but they are as important to me as technical writing. Getting things into focus, presenting a more balanced view - it's just a matter of thinking of myself in the active voice. My active voice.

Don't ask me how this ends. I just woke up.

Does it have a hyphen?

2009-05-14T20:47:00.005-05:00

Years ago, I discovered that the surest way to throw a roomful of technical writers into an uproar is to ask, as innocently as possible, "Does the term 'anal-retentive' require a hyphen?"
Don't take my word for it. Try it yourself - but only if you've already concluded the business at hand, and still have an hour or two to spare.

Spirited discussions of grammatical questions are like crack for writers. They give us such a buzz every time. We feel so great, so smart, so right. It's what we live for. We can't stop. We can't get enough. We don't want to hear that they interfere with our lives and damage our productivity, and we really don't want to hear that they're an inappropriate use of a designated meeting time or discussion forum.

The only difference between writers and crackheads is that we're not likely to get arrested for possessing grammar books. Today I witnessed this truth play out in a dramatic, time-consuming, and very public way.

As in music or dance, it's impractical to strive for perfection in writing. We have to settle for attaining a level of skill that allows us to make a living at it. And our goal must be to communicate effectively, rather than to be excruciatingly correct. A technical writer's mission is to help people understand things. If we have to make a choice between clarity and correctness, we have a professional obligation to choose clarity; though in almost every case a bit of rewriting will allow us to serve both those masters.

Most of us are acquainted with the anecdote usually attributed to Winston Churchill: Upon seeing one of his sentences rewritten in a cumbersome fashion to keep it from ending with a preposition, Mr. Churchill allegedly said "This is the sort of nonsense up with which I will not put."

Regardless of the true origin of the quote, the point is valid: Clear communication is the objective. Get the grammar right enough that it doesn't interfere with your message - that is, right enough that it doesn't strike your audience as wrong - and move on. It's one more matter that comes down to knowing your audience, and recognizing that sometimes tech writers are not the audience.

I might get into tech writing

2009-05-06T13:47:00.006-05:00

"Hey, how are you doing? What have you been up to, the last few months?"
"Oh, I'm doing all right. Looking for a job, though."
"Yes, I got laid off recently, too."
"You know, I was just thinking about getting into technical writing..."

This conversation bothers me every time I find it playing out - which it does so often I wonder if I'm in a time loop, like "Groundhog Day". The last time around, a few days ago, it was time to dig into the question of why it bothers me.

I know this is meant as an expression of interest in my trendy and lucrative profession. I know it is not meant a subtle variant on "Anybody can write."

Still, I can't picture myself saying to my friend, "You know, I've been thinking about getting into engineering," or "I've been thinking about getting into project management." I would sound presumptuous, at least to my own ears. I've been a technician and and engineering assistant, but I don't have the training to be an engineer. I took the coursework from the Project Management Institute, but did not sit for the PMP exam. If I were to consider becoming an engineer or a project manager, I would need to start by becoming qualified to do the work.

Within the Society for Technical Communication, the idea of certification for technical communicators resurfaces from time to time; to date I've opposed it because the Society hasn't ever worked out what that would entail. But now an effort is under way to develop a body of knowledge (BoK), which has been the missing piece. Once the Body of Knowledge is declared ready for use, I will have a helpful answer to my friends who speak of becoming technical writers. I'll be able to point at it and tell them, "Here is a good place for you to start."

The STC Body of Knowledge is in progress at http://stcbok.editme.com/ - take a look, or contribute.

Reclaiming the boxes

2009-05-04T22:53:00.004-05:00

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.

2009-04-08T20:44:00.003-05:00

I've spent the last two weeks grinching and groaning and generally boring people with updates on my car, as that sad tale unfurls in a leisurely fashion. Bumper sticker version: My car got badly damaged by hail, and was declared a total loss - but only after it was declared worth repairing, and I'd gotten my hopes up.

This morning it dawned on me that I was dealing with this sudden, forced change - give up my sweet car? no no no! - exactly the way people "down the food chain" in organizations deal with sudden, forced change; which is to say, exactly the way four-year-olds deal with it.
I want my doll back! Make her be not broken!
I want my car back! Make it be not broken!
I want my business process back! Make it be not broken!

The irony is that I'd just told someone "You need to let go of this process you use; it's broken."
And of course I'd gotten back, "No no no! I want my process! It isn't broken, its head is supposed to come off like that!"

For years I've known in my head that you have to manage change carefully to introduce it successfully. You've got to get people excited and happy about what's going to be different; otherwise they'll resist it in every way they can. Over the last two weeks I've been absorbing that lesson into my heart.

I should go give blood while my irony level is up so high.

Packaged on: 05APR09 Sell by: 04APR10

2009-04-05T14:27:00.005-05:00

I just looked at the date on my last post - it's very stale material by now. I'm sorry. There were reasons for the silence; chief among them being that sometimes it's the better part of valor to sit down and shut up. (Natural disaster, badly damaged car, much to-ing and fro-ing with insurance company and body shop, if you must know.)

But I'm back now.

Recently I saw some product documentation that clearly needed work. Certainly it needed the deft touch of a good technical writer; but what struck me first and hardest was that it needed to look like a product of this millennium. It seems the company had designed their documentation and the process for creating it some time in the mid-1990s, and had been using early documents as templates for later ones ever since. Meanwhile the world kept on advancing; and with it, documentation conventions, tools, and best practices.

With few exceptions, we need to step back and look at our organizations' product documentation about every three years, or every time our colleagues the marketing specialists update the appearance of the company web site and marketing materials. During these periodic reassessments, we need to ask ourselves, "Does this material reinforce our organization's main message? Does its appearance reinforce and expand upon the first impressions that our marketing material and web site create? Does this look like it comes from the same company?" We also need to consider whether we still deliver our material in the way customers expect to see it. Are we still writing software manuals instead of providing help? Are we still using section numbering when all our competitors have stopped doing so?

Marshall McLuhan said "The medium is the message", and that's far truer now than it was when he said it. The words and pictures are not the sum of your product documentation. The words, pictures, look and feel, and delivery method all work together to produce a powerful message about the product and the company. It behooves us to ensure that the message never becomes "We have been doing it this way for the last fifteen years and we're not about to change."

Tina the Technical Writer doesn't work here

2009-03-16T10:49:00.003-05:00

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.

The idea that wouldn't die

2009-03-12T16:57:00.004-05:00

Some ideas sound great for about five seconds, and then gracefully go away. Some sound uninspiring at first, but gradually reveal their brilliance. And some ideas sound like Manhattan Projects for opening pickle-jars, but they just won't go away. Exhibit A in this category is the idea of certifications for technical writers.

Full disclosure first:
I do not meet the educational requirements so loved by personnel departments. I have never studied journalism or English, beyond the bare minimum. I do not have a bachelor's degree in anything. I have a trade-school degree in electronics. I became a technical writer more or less by accident. So I don't like the idea because it might mean my résumé and sheaf of awards might not be enough to get me in the door for interviews.

Let's step back, though, and think about this.

What problem are we trying to solve?
There's no arguing the fact that in every profession, there are people who just aren't any good at what they do; and it's hard to get rid of them once you've hired them. It would be easier if there were a way to avoid hiring them. There is; but it requires knowing something about the work. Organizations hiring their first technical writers don't have that expertise; but they need to get it right the first time. So there is a real business problem to be solved.

Many professions use certifications, some with more success than others. I respect people who are certified project management professionals. I know the effort it represents, and I know the range of skills upon which it focuses. I respect people who have been certified as professional engineers; again, I know that the letters "PE" after the name represent a great deal of work and a fair degree of skill.

I'm not nearly as comfortable with teacher certification, because I'm not persuaded that it's meaningful. I've dealt with far too many teachers who could be described at best as mediocre. Go ahead and flame me. In ninth grade I had a science teacher who could not do sums. (Hey, here in Texas we are all about equal opportunity.) Is it possible to create technical writing certifications that are more meaningful than teacher certifications?

To be useful, certification needs to do three things:

Correctly identify the essential skills of the profession.
Assign them appropriate importance relative to one another.
Test them in a valid way.

The sheer diversity of work that comes under the heading of "technical writing" makes it difficult even to identify a core skill set. Is there a meaningful "common denominator" among all the skills represented in our profession?

I was once hired as a technical writer for a job that involved no writing at all. I was to add conditional text tagging to existing material in such a way that the team could produce manuals for new products without changing the text and conditions already in place for existing products. I have had technical writing jobs that included extended periods of creating pictorial instructions only. One might think that any technical writer should have an excellent command of grammar and punctuation; but would it have been meaningful to require proficiency in grammar and punctuation in these situations?

Should we even think of technical writing as a single profession?

Many have suggested specialized certifications to address this. But technology moves quickly, while certifying bodies move slowly. What's going to be the good of having a ten year old certificate in web design? The only solution I can see is to certify people's understanding of concepts rather than implementations. Don't certify people in web design; certify their understanding of usability, searchability, and accessibility. Don't certify people in writing manuals; certify them in organizing information and knowing when to show rather than tell.

That might actually work.

Anything is possible = Nothing is possible

2009-02-27T22:37:00.005-06:00

I was looking at FrankenLoom this evening, rather than weaving on it. FrankenLoom started as a simple frame loom of the sort that Navajo ladies use to weave those beautiful rugs; but because of a horrible accident during a radiation experiment (or something), FrankenLoom ended up with some bizarre extra attachments. At some point I will finish the triptych taking shape there.

It occurred to me that all the extra bits on FrankenLoom do one thing: They constrain what is possible; and yet they sprouted there to make the current workpiece possible.

A loom with nothing on it is like a blank sheet of paper or a blank screen: Anything is possible. But if you are a handweaver, you know that you cannot weave an "anything". You have to prepare the loom by putting the warp threads in place; and in doing that, you constrain the dimensions, weight, color, and texture of the cloth before you even start making it.

So too with writing. That blank screen could lead you anywhere; it opens up an expanding sphere of infinite possibilities, and so nothing happens at all. We begin to write only after we have set the constraints. What are the limits on the dimensions, weight, color, and texture of this thing I am about to write? In weaving as in writing, the preparatory work to set those constraints is often tedious and formulaic; but in both cases, a few experiences with slapdash preparation teaches us the patience to do it right. When we give thought and care to getting "the boring part" right before we start, "the fun part" is more fun - it goes faster for being more nearly trouble-free, and the finished work is of visibly superior quality.

There's surely a message about deferred gratification in there somewhere; but I've learned to find gratification - and to feel gratitude - in setting the constraints that move me from "anything is possible...what now?" to "this particular project is possible, and it's going to turn out very well." The project schedule, product feature plan, information plan, outline, template, and style guide all set constraints. They are the weapons with which I vanquish the frightful monster that is the blank screen. They are the threads with which I warp the loom on which I weave my words.

What do you want?

2009-02-17T23:29:00.008-06:00

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.

Manuals are not the point

2009-02-15T21:41:00.000-06:00

With the sole exception of my first technical writing job, every time I've been hired as a writer, it's been by someone with a vague notion that their organization needed manuals. More manuals, better manuals, up-to-date manuals.

We technical writers tend to justify our jobs by saying our employers or clients need manuals and help systems, and usually that's where it ends. We sound like Mr. L. Prosser, the road construction foreman in the opening of Douglas Adams's book, The Hitchhiker's Guide to the Galaxy, justifying the demolition of the protagonist's house by explaining that they're building a highway bypass, and "you've got to build bypasses." Press a technical writer to explain why our employers or clients need manuals and help systems, and things get vague fairly quickly.

The truth is, you don't need manuals. You need the right product documentation, delivered in the right medium to meet your customers' needs. The business case is very simple: It saves you money, and it saves your customers money.

The wrong material, though - a poorly organized manual, or a help system that focuses on what the product or service does instead of the tasks your customers want to accomplish with it - is worse than no manual at all. It frustrates your customers. It undermines their confidence in your product or service.

The right product documentation gives your customers the confidence to set up your product or service and become proficient with it faster than they would otherwise. Just by reducing your customers' time to success, you've saved them money.

Beyond building your customers' confidence and getting them from zero to success quickly, you've also avoided the all-too-common technical support call in which the customer says plaintively, "I can't figure out how to set this up." If your organization doesn't have a technical support function, your engineers or developers may be the ones talking your customers through basic steps. All the goodwill in the world won't make up for the drain on their time and the interruption of their thought processes. Worse, if a customer has trouble using the product documentation and places a technical support call instead, you've just induced and reinforced this costly behavior.

With the right product documentation, your customers feel confident enough to take their first steps without asking for help - and when they realize they can easily find the answers to their questions in the documentation, they only call technical support if something isn't working right. Your engineers spend their time engineering, your developers keep on developing, and your customers gain confidence in your product or service.

No more peanut butter sandwich exercises, please

2009-02-12T22:27:00.000-06:00

It seems as though any time I meet someone and the conversation turns to what each of us does for a living, as soon as I say "I'm a technical writer," my partner in conversation is seized with a desire to tell me about some technical writing exercise in high school or college. "The prof showed us a cheese slicer, the kind with a wire and an adjusting knob, and told us to write instructions for using it. We were supposed to write it for someone who had never seen one - like a Martian or something."

My daughter told me about the peanut butter sandwich "technical writing" exercise, made livelier when the teacher dipped her hand into the peanut butter because nobody had specified that a butter knife be used. My own brush with this kind of exercise involved describing an everyday object in exacting detail, as if making a mechanical drawing with words, and explaining what each part of it does.

All these "technical writing" exercises seem to bear that same requirement: Write it for an audience that has no idea what you're talking about. They are all entertaining exercises - if you are fond of useless precision and work for work's sake - but they have almost nothing to do with technical writing. Can we please stop inflicting this silliness on students?

Never in my career have I written instructions for installing and using a frabbetizer, and expected that the people reading those instructions would be completely ignorant of the appearance and purpose of a frabbetizer. The instructions are in the box with the frabbetizer, or the frabbetizer help is part of the frabbetizer download. One way or another, they've got the silly thing in front of them; nobody ever reads a manual on the bus. So I don't have to describe the frabbetizer, beyond pointing out where to connect things or find non-obvious controls. In most cases, they know what it's for already, or they wouldn't have bought it. To address the case of the guy who's mystified by the box that the receiving department just left on his desk, I'll write a paragraph at the beginning of the manual that briefly describes what the frabbetizer is for, and includes some magic feel-good words: "The Model 2500 frabbetizer is a powerful, compact, and cost-effective reputation-polishing device for small organizations. Its small footprint, attractive walnut case, and unsurpassed ease of use make the Model 2500 a popular choice in home offices and start-up businesses." OK, now you know what a frabbetizer is, if you didn't before.

Having ensured that the reader knows what a frabbetizer is, our next step is to talk about all its parts and explain what each of them does, right? Wrong. Nobody cares what the parts do. So we're not going to do that.

Our next step is to talk about what the reader can do, and how to do it. Here's how to switch on the power; here's how to log on; here's how to set up your account; here's how to polish your reputation using the frabbetizer. We are not ever going to get into the nuts-and-bolts details of exactly how the frabbetizer polishes reputations, because nobody cares. Correction: no customer cares. That's all that matters.

Of all the sins a technical writer can commit, there is no sin so great as boring the reader with useless information - and that's exactly what those classroom "technical writing" exercises do. So let's put a stop to it. Students would be better served if the exercise involved identifying the audience for whom they are writing, and writing to the appropriate level.

The trouble with naming things

2009-02-11T21:48:00.000-06:00

It's hard to think up a good name.

In many "primitive" cultures, naming is a magical act. To name is to define. Knowing the true name of a person or thing confers power over it.

Maybe we're more primitive than we'd like to think. Years ago, when I heard about a guy running for mayor in Austin, Texas, I thought "That guy was born to go into politics." His name is Will Wynn, and he did win.

But when you're on the spot and you need to name something - a business, a product - it's hard to think up a good name.

Part of what makes it hard is that a name may mean something you didn't mean it to. I know of a company that designed a new high-tech product and planned to call it the model 420. (If that is not a funny statement to you, go to Wikipedia and enter 4:20 in the search box.)

Complicating matters is the fact that a set of sounds may mean nothing in your language but might have a meaning in some other language. Another company I know of once planned to introduce a new product as the "VQ", until a French person explained that they had best call it something else. ("Vieux queue" is not a phrase normally uttered in a business context.)

Then too, no matter how innocuous and straightforward the name, some people are going to mess with it if they possibly can. My daughter shops at a store called Grocery Outlet. Being a wise-acre college student, she shortens the name to "Groce-Out".

Even the pros goof up some of the time. In one of those two bad-product-name anecdotes, a product naming consultant was paid a huge amount of money and still ended up presenting an unusably bad product name.

I don't have a good answer to the problem of coming up with a good name, other than trying it out on as big and diverse a collection of people as possible. So I'll just hope I don't end up the subject of a story about a poorly chosen name.

Warnings that don't work

2009-01-23T16:54:00.000-06:00

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.

Adequate vs. award-winning

2009-01-16T16:22:00.000-06:00

When I accepted a job with my most recent corporate employer, I promised the company's three founders that I would deliver award-winning documentation for their products. Then I delivered - three awards so far, with another one possible this summer.

Thinking about this last night, I asked myself: What makes the difference between an adequate manual and an award-winning manual?

The answer is the same as it would be if we were talking about cars, houses, cleaning services, wedding cakes, shoes, massages, or anything else that people do or make for other people: attention to detail. Doing all those bothersome little things that take time and effort but don't individually make much difference - because in the aggregate, all those bothersome little things make a very noticeable difference. For example, it takes time - minutes or hours, depending on the material - to make sure all your chapter or book titles and section or topic headings are grammatically parallel; but when you've done that, the table of contents reads well. Still, it's a bothersome little task that people often skip. By itself, this won't vault your good manual into the winner's circle, but if you do it along with all the other "detailing" that's involved in polishing a document before publishing it, you'll end up with a much better document.

If you want to deliver a superior product, start with a good product and a list of all the bothersome little things that people often skip in the name of holding to the schedule or keeping costs down. Then nail every item on that list. That's how you go from good to great.

Recipes, assumed knowledge, and indexes as teaching tools

2009-01-09T12:47:00.000-06:00

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.

Why printer specifications don't match your experience

2009-01-08T13:52:00.000-06:00

Yesterday I read a detailed, helpful, well-written review of a new printer. The author covered all the things I'd want to know about when making a purchasing decision. A lot of the article was about how the performance numbers seemed exaggerated - testing showed that the printer didn't go nearly as fast as the published specifications would indicate. The author seemed surprised at this.

Excuse me while I change hats. There's a bit of dust on my printer R&D technician hat - ah, here we go. I will neither defend nor condemn the way that manufacturers arrive at performance specifications; but at least I may be able to explain them.

You will NEVER get the advertised speed from your printer. It does not matter who manufactures it; it does not matter whether it is a home-office desktop printer or a big high-throughput monster that the installers set on steel plates to keep it from wearing holes through the carpet. It does not matter whether it is a laser printer, inkjet, or some one of those obsolete technologies such as daisy-wheel. When a printer manufacturer publishes the technical specification for a printer's speed in pages per minute, that number represents the best speed obtainable in the test lab. If the printer is listed as a 20 page per minute printer, that means that it's able to drop 20 pages per minute into the output tray if you send it a huge print job consisting of nothing but page break characters.

How does that 20 pages per minute figure relate to actual experience?

Getting a print job started takes some time; you'll see lower average print speeds on short jobs than long ones, because the set-up time isn't all that much different for different sizes of print jobs.

If you ask your printer to actually make marks on the paper before ejecting it into the output tray - as most of us do, most of the time - that will slow things down. If your representative page in a long print job is about 30% covered with text (as for a letter or pages in a manual), your printer may do 15 to 17 pages per minute. This will be lower for short print jobs - maybe under 10 pages per minute.

If you want the printer to make marks on both sides of the paper, that will slow things down more. Even counting each sheet of paper as two pages, the speed will be lower than one-sided printing because of the time it takes the paper handler to flip each sheet.

So why do printer manufacturers not give comparison numbers from real-world testing? Would it be so hard to devise standardized testing - say, files consisting of varying numbers of pages of "Lorem ipsum"?

The other number that's likely to cause people to become unhappy with their printers is the "duty cycle" - how much of the time the printer is in use. The assumptions about how often a printer is serviced and how often it is likely to break are based on this purely hypothetical number, which is usually 25%. It's natural to assume that "25% duty cycle" means it's running 25% of the time, or 42 hours per week - but duty cycle is calculated on a 40-hour work week, not a full 168-hour week. So if your printer is rated for a 25% duty cycle, that means you are overworking it if it spends more than 10 hours a week printing. You'll hear about that from your printer service representative, who will probably urge you to get a high-output printer. It's probably good advice. You may feel as though you're being asked to trade an economy car for a luxury car, but it's more a case of not riding your moped on the freeway.

Vendors and leasing companies could save themselves a lot of explaining - and save their customers a certain amount of aggravation - by explaining how the speed and duty cycle numbers are derived; but printer manufacturers could nip these problems in the bud by adding text-printing test results to their specifications, and changing the way they calculate duty cycle.

Full disclosure: As mentioned earlier, I used to be a printer R&D technician. It has been many years since I had any connection to the printer business. Buy whatever printer you want, or hire a calligrapher - it's all one to me. :-)

It can't be that hard

2009-01-03T16:29:00.000-06:00

When did you last buy a new techno-toy...
...look at the manual...
...carefully put away (or carelessly throw away) the manual...
...and say "I'll work it out on my own"?

When did you last get stuck trying to figure out a new techno-toy on your own...
...heave a deep sigh...
...and consult the manual - only to find that it made you feel as though your head might explode?

Is it just me, or does the average manual make things sound hard?

It's a new year. It's a good time for a new view of things. Try this on for size: Nothing is as hard as it sounds when your subject-matter experts tell you about it. Nothing. Because inside every arcane, elegant, hackish implementation that takes half an hour to explain is a beautifully simple idea. As technical communicators, it's our job to listen for the faint, pure song of that simple idea. It's our job to tune out the cacophonous techno-babble that normally drowns it, and let the music of that simple idea be heard loud and clear.

Sometimes we get push-back from our subject-matter experts if we strip away the tech talk - particularly if they have taken the trouble to write explanations for us. (This, by the way, is as good an argument as any for never asking your subject-matter experts to write anything for you.) But I've found that I can win over even a fussy subject-matter expert by explaining that I am trying to showcase the brilliance of the design, and that customers will see it more clearly if it's in layman's terms. True brilliance in product design is in implementing a simple idea and concealing the complexity of the implementation. The people at Apple know this, and it's made the company a huge success.

It's not just Apple. There's a lot of talk about Web 2.0 being all about user-generated content, but what makes that possible is the true core of Web 2.0: If it's hard, nobody will use it. Everything is easy.

Hard to use, hard to read, hard to understand - we're done with that. Everything is easy.

How does your product documentation look? Find the essential simplicity and take out the rest.

The service manuals of yore

2008-12-29T16:10:00.000-06:00

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.

Getting out of the box

2008-12-27T23:41:00.000-06:00

Anybody can write - right?
Sure.
But do you want just anybody writing the help or the administrator's guide for your product?

Your product development team has worked hard to bring a vision into being. You wouldn't have spent the time and effort on it if you didn't believe - passionately - that the project could meet your customers' needs in a way no other product can do. Your team wouldn't have put their hearts and souls into developing this product unless they believed in it. Doesn't your team deserve to have their brilliant work showcased? To put that another way: Shouldn't you give this product the best possible shot at success?

Great product documentation shows your customers how simple it is to use your product, and makes them want to try out all its features. Because as complex and sophisticated as the design may be, as elegant as the code may be, what's going to sell your product is the perception that it's robust, reliable, and easy to use. Great product documentation gives your customers the confidence to get familiar with the product - and once they've cleared that hurdle, the product looks a lot easier to use.

What does great product documentation look like? Like Supreme Court Justice Potter Stewart, you probably know it when you see it. But what is it that you see?

In great documentation, you see little about the product's capabilities or design philosophy. Instead you see information about how people can use the product to accomplish what they want to do. It's about your customers first.

It's easy to make the business case for top-notch product documentation - be it installation drawings, administrator's guides, quick tip sheets, or help: If that's part of the package, you'll win more competitive evaluations, and you'll spend less on technical support. And amazing as it may be, it takes fewer words and less time to communicate the people-centric information that your customers need than the design-centric material that they dread - so even the direct cost of creating great product documentation is lower than the direct cost of creating lower-quality material.

Move your product documentation out of the box. Put it on the winner's platform - along with your great product.