Prioritising technical documentation

Saturday, 19 February 2011 05:15

Are some of your technical documents more important or more sensitive than others, and if so does that mean that you should pay more attention to them when time or resources are short?

As a technical writer, I’d like all our documents to be perfect. Each and every page should sing. It should be aesthetically pleasing, concise, correct, complete, up to date… you know the score. But sometimes that’s just not possible. Time and budget get in the way.

In this post I’m thinking about the maintenance of existing documents, rather than the development of new documentation.

Sensitive documents

Recently I’ve been thinking about the fact that some parts of our technical documentation are more sensitive than others. By “sensitive”, I mean that people have stronger feelings about what’s in the document. People even watch the pages carefully, to see when and how we change them. Whoever said that documentation isn’t an emotional experience?

Some sensitive documents:

Security advisories. (Example. And I’ve written a post about the roller-coaster ride of writing security advisories.)
Documentation about supported platforms. (Example.)
End-of-support announcements. (Example.)

Important documents

Defining what’s more important is a sensitive topic in itself. It depends on your point of view. I’d argue that the installation guide is top of the list. After all, if people can’t install the product they’re not going to need the user guide, are they?

If the installation procedure is so clever and simple that the product installs itself, then a task-based and domain-focused getting started guide must be top of the list.

Prioritising the sensitive and important documents

Let’s assume we’ve decided on the most sensitive documents (those that the customers watch most closely) and the most important (those that help people get the product going). How does that affect the way we work and the attention we pay to the documentation?

Here are a few of the possible consequences:

When people add comments to the pages, or give us feedback in some other way, we respond as quickly and comprehensively as possible. If time is really short, the least we can do is recommend that people raise a support request to fix any problems they have.
At each product release, we test the instructions on the page to ensure that they’re still up to date.
If anyone edits the page, we take a look immediately and revert or correct any mistakes.

Sensitivity of another sort

On Thursday I decided to work from home. Got in the zone. Glanced at the window sill. Eek. Eeeeek! Biiiiiig spider! Not moving? Phew, not a live one, just the shed skin.

Even so, it took a lot of rationalisation and calm conversation with myself before I got close enough to place the battery for perspective and take the photo.

It’s actually a gorgeous and marvellous creature, but spiders are a sensitive topic for me.

Which bits of your documentation are sensitive or important, and how does it affect the way you work when time and resources are short?