Creating Useful Documentation

Knowing the people

So far, I've just been talking about understanding the field for which you are writing in order to produce useful documentation. The next important key to creating useful documentation is knowing the people for whom you are writing.

I don't mean you should go out and carry on personal contact with every person who uses the product. You do, however, have to become familiar with the mind set, attitudes, experience, and education level of the users. Experience and education level is especially important. Writing about book keeping software for accountants with years of experience in fortune 500 companies is a far different exercise than writing for the owners of a mom-and-pop shop who have never used a computer before. You will find that understanding the people will give you clues as to what sort of information you must include in documentation and what sort of information you can leave out.

Some common ways to get to know the users are to:

Have experience with the field or people in the field
Interview users
Interview your company's QA, R&D, training, and customer service personnel

Having experience within the field the product belongs in or even just knowing people who use or would use the product you are writing for helps out a lot. After all, if you are busy making 3D animation you are theoretically in contact with other people who are doing the same thing. If you have friends who are involved with the product (or similar products) you can chat with them about what they find particularly annoying about the documentation in the field (something almost everyone will gladly do) or have them point out things they would like to see in documentation.

Closely related to talking with people who participate in the field is interviewing the actual users of the product for which you are writing. If it's possible, getting in touch with your users is the best way to get to know them. You can then ask them point blank what they want to see in the documentation. They can tell you what areas of the product and its documentation are confusing and need more detailed descriptions and what parts can be lightly covered. Interviewing users can be an expensive venture for some companies, and it will definitely take time away from the documentation development cycle. However, if you can convince those with the purse strings to do it, user interviews are a great way to get excellent (and not so excellent) feed back.

Finally, your coworkers are a valuable resource. Trainers and customer service have direct contact with the users. They can tell you about the mind set, attitudes, goals, experience, and education level of users. QA and R&D may also have a feeling for the personality of users. These resources can highlight trouble areas about the product or its documentation. They can also give you an idea for what works and what's useless.