Prioritising technical documentation

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:

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 πŸ˜‰

Prioritising technical documentation

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?


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 19 February 2011, in technical writing and tagged , , , . Bookmark the permalink. 9 Comments.

  1. Hi, Sarah-

    Everywhere I’ve been, release notes have always garnered the most attention. That’s often the place where an organization spills the beans on the real status of a release, and much of the content could be considered “delicate”…. πŸ™‚


    • Hallo Arnold
      You’re right, that’s a good one! Release notes attract a lot of attention. People often comment on the pluses and minuses of a new feature and suggest further improvements to the product.
      Cheers, Sarah

      • Btw, that is a really ugly spider…skin or not, I’m not going to be able to sleep tonight!

      • Heh. It’s a huntsman. They’re not considered dangerous, though they can give you a painful bite. They move incredibly quickly, sometimes too quickly for the eye to follow. It’s almost as if they flash into a parallel universe. They will also jump at you, rather than away, if they feel threatened.

        Sleep well. Mwuaaa ha ha. πŸ˜‰

  2. According to reports by my users, everything has top priority and should be attended to as a matter of the utmost urgency. πŸ˜‰

    But really, for me the getting started guide goes to the top of the list. I am documenting an application for the analysis of scientific data, which must be obtained from a remote server, in a less-than-intuitive way.

    Without data, users can’t even begin to tinker with the application. And they get frustrated really quickly. πŸ™‚

    By the way, am I the only one who finds that spider adorable?

    • Hallo Davide

      Plus one for guides to getting started.

      I even managed to pick up the “spider” once I’d persuaded myself it really really was just an empty skin. Then I promptly dropped it, with a small but piercing shriek, because one of its claws clung to the wood, persuading the primitive parts of brain that it was alive after all. πŸ™‚

      I like the idea of your revived blog, to focus on free and open source tools for tech writers!

      Cheers, Sarah

  3. Hello Sarah,

    Still wondering if I’ll rembember the real content of the blog or the spider.
    Don’t have those spiders here..


    • Hoi Bram πŸ™‚

      I hope the spider doesn’t give you nightmares! Actually, we have far worse ones here. The Red Back is very venomous and quite common. I’ve encountered a number of them. They’re much smaller, black and pudgy. Then there’s the Funnel Web, also rife in my area. Luckily I haven’t met one yet. They’re deadly.

      Getting back to the “real” topic if this post, I’m guessing some of us have nightmares about particular documents too…


      Cheers, Sarah

  1. Pingback: Tweets that mention Prioritising technical documentation Β« ffeathers β€” a technical writer’s blog --

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: