Doing the needful

Doing the needful” is an Indian English expression that I picked up from former coworkers. I’m currently managing a training development project, and that’s leaving little time to work on the product documentation. So I’m focusing on what I earlier called “moving the needle”; or in other words, figuring out what among the tasks that I’m responsible for is most in need of doing.

A few words about training

The curriculum developers are reading the existing product documentation, looking for content to mine. This is good for two reasons:

  1. Someone’s actually using the docs! That’s always awesome.
  2. They’re reviewing the docs, asking some very pointed questions, and poking at areas that are a bit thin on content.

Any brief ego boost you get from #1 will dissipate quickly once they start asking those pesky questions. Like, “But how does the product really work?” or “I don’t understand.”

No plan survives contact with the enemy, and no documentation survives contact with your customers.

Not that your customers are your enemy. And some users will probably be fine with your docs as they are. But that’s not the point.

I’m referring to people using your documentation to understand your product thoroughly enough to be able to teach other people how to use it.

For most of your customers, that comes after they’ve read some of the docs, maybe run through a few tutorials, and have spent a few months, maybe years, using your product.

Obvious things are obvious

You know what’s fun to write? Really easy instructions, like how to open or save a file. Those are easy to write, and give me the satisfaction of quickly checking a task off the

You know what’s completely useless to most of your customers? Topics like that.

If a topic is too easy to write, it’s too easy for most of your readers to care about.

The tricky thing is that those topics might get a lot of pageviews. Readers will look at those topics just in case there’s something interesting or unusual there. After all, if you documented “How to save your project,” then there must be something strange about
how your product saves files, right?

They won’t be impressed if the topic tells them nothing more than “Select File > Save. Click OK in the ‘Are you really sure you want to save?’ dialog.”

Never fall in love with your own words

The good news is that your customers won’t let you fall in love with what you write. Neither
will your development team.

Customers will request more info and new examples. Your dev team will add, remove, and change features. Sometimes they’ll even tell you when they do that.

The good news, in a way, is that in an agile development environment you won’t have time to craft the perfect sentence. It’s all about creating a good enough solution, and then moving on to the other things you need to document before the next release.

But what’s the point?

This sounds like a case of Sisyphus and the rock, but I think it’s what keeps techcomm exciting. The development cycle doesn’t stop, the product you’re documenting keeps improving, and your documentation product needs to improve at the same time.

“Improve” for content means increased accuracy, readability, accessibility, and generally easier and less expensive to produce.

The most basic measurement is this: Does your documentation reduce support costs, improve the customer experience, and increase customer adoption of your product? Anything that doesn’t move those needles isn’t worth doing.

Eliminating typos in your documentation might be personally satisfying, but unless they impede understanding that’s a very low priority task. (But if your authoring and publishing process is agile enough, then it can also be a low effort task.)

Even better is when you can quantify those tasks. In an ideal world, you’d be able to say, “By writing these topics, I’ve reduced support effort by 10%.” That number can be directly translated into cost savings for your company (which is very much like making a profit).

Quick note: I’ll be at IDW this week!

And a quick reminder that I’ll be attending the Information Development World conference this week. I’ll also be part of the Management Issues in Information Development panel at 11:45am on Friday. Stop by and say hi!