Writing good technical documentation, part 1

A recent comment by "BPM software" suggested that I write about best practices for writing technical documentation. I thought about it for awhile and decided I couldn't really do it justice in one post - hence, "part 1".

I'll begin by plagiarizing myself. What I said about management packs is just as true in this context:

Ideally, good technical documentation tells you everything you want to know and doesn’t tell you anything that you don’t want to know.

The key in that statement is you. Whether the content is good, whether it answers your questions, whether it avoids wasting your time with irrelevencies...all of those are defined by you, the reader.

Just about every book/class/seminar/workshop on communicating effectively starts at the same place: know your audience. Why? Because I have to know who you are so I can figure out what you'll want to know and what you don't want to know. It's really easy when it's 1:1, like when I write up instructions for a relative.

There are just too many readers in the professional world, though. So technical documentation tends to become "everything anyone might want to know" because we usually prefer to offer at least some value to many rather than great value to just a few.

So, the first best practice is to define your reader (customer, user) as best as you can. To document software, I consider the two main questions to be:

1. What does your reader want to do?
2. What does your reader already know?

To answer the first question, you need to learn about the problem your reader has that he wants to solve, about the environment he'll be in, and about his expectations for a solution. All of this information helps you define what the reader wants to know and, in combination with the answer to the second question, helps you define what he doesn't want to know.

Your answers to the questions may also reveal that you have more than one type of reader. Take Operations Manager, for example. We have customers who want an efficient method to monitor many servers. We also have customers who want an easy way to create their own custom monitoring solutions. Some of those customers are support technicians who want documentation that will help them monitor and some of those customers are developer-types who want documentation that will help them create customized solutions. So right there we have two very different readers who need distinctly different documentation.

When your readers have different goals and different levels of knowledge and experience, don't try to write to all of them in one document (if you can avoid it).

I'll be honest, we're not fully there yet with Ops Mgr. Some of our documentation tends to skirt between those two readers. We recognize that we've muddied the waters a bit, which serves neither reader very well, and we're working on repairing that problem in future versions.

Comments

• Anonymous
  January 01, 2003
  (Part 1) Joel Spolsky has an excellent post on the role of the program manager . I work with program