Cooking up good technical communication

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

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

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

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

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

An hour later, it’s delicious.

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

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

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

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

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

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

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

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

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

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

Except...

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

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

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

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

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

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

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

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

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

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

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

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

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

"Awesome."

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

Over the Threat-Level Rainbow

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

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

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

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

Here's the text in the graphic:

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

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

What should we do better?

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

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

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

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

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

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

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

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

The Tribal Knowledge Project: Getting off the ground

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

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

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

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

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

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

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

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

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

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

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

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

Seven Habits of Highly Defective Technical Writers

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

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

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

How to develop X-ray vision

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

My job is not me

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?

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

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

Packaged on: 05APR09 Sell by: 04APR10

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

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

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

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?

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.