Saturday, May 12, 2012

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.