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.

The Tribal Knowledge Project: Facing Reality

A couple dozen of us at BlobCo have started a project to collect and share the deep, secret knowledge of the gurus on our technical staff - those amazing people who can get to the bottom of any customer's problem, no matter how intermittent or bizarre. They know things the rest of us don't, and we'd all be more valuable to our customers if we could learn what they know.

I've been given the extraordinary privilege of coordinating this effort. I don't think of it as leading, because all I'm doing is facilitating the process of deciding what to do and how to do it. Later I'll organize the information that comes out of the project. These are things I do anyway, as part of my job, so it doesn't feel like I'm doing any leading. Maybe steering a little, since I have deep, secret knowledge of how to collect and present information; but it's the folks in the front of the canoe who will keep us from smashing up on the rocks in the places where the water flows fast.

We have about one big mental breakthrough a week. I don't know about you, but that's enough to keep me really excited about the project. At our last meeting, the big idea was to work in teams of two or three to work out the process for solving each of the problems on our list.

But things are getting busy at BlobCo. We have a product release coming up. On top of that, everyone who's not involved in that is getting ready for a big conference. And this project hadn't even been imagined when people figured their headcount requirements for the year.

One of the technical services people came to me quite upset that she wasn't going to have time for the project for a while. Time to deal with reality. Since it's crucial for me to keep the project from becoming a burden, I let everyone know we were calling a halt to work on the project until after the conference and product release. When I updated the VP of Mumble on our progress, I explained this decision, and he agreed - he needs his people to focus on the company's current priorities.

The Tribal Knowledge Project will go live again next month. I'm looking forward to continuing our adventures.

The Wisdom of the Crowd: Prologue

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

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

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

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

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

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

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

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

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

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

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

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

What happens next?

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

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.

New Year's Resolutions

...need project management.

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

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

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

OK, STOP IT RIGHT NOW.

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

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

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

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

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

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.