Software Documentation

Lesson 2: The Importance of Audience

The audience is a key element that many people fail to consider. When your job is to convey knowledge to someone, you need to understand what that person already knows and develop a sense of the teaching methods likely to work for that person. If you're writing instructions for a customer service representative don't assume they understand database theory or any of the associated terminology. It sounds obvious, but the failure to properly analyze intended audience is the single largest pitfall facing technical writers.

Examine the software to determine your user base

If you don't understand your audience then chances are you won't be able to write documentation they'll understand. Evaluating your audience can be a difficult task but it is absolutely essential you do so. The best way to start analyzing your audience is by evaluating the product you need to document. You can tell quite a lot about your intended audience from the software since they are also the intended users of the software.

If you're tasked with teaching developers how to write front ends for your product using Visual Basic, then you already know quite a lot about your audience. You know:

They are developers
They know Visual Basic
They are familiar with user interface design

In actuality, perhaps some of your readers will not fit this description, but it is your task to define the supported skill set, make it clear to your readers what you expect them to already know, and then write the book as if they know precisely that - no less and no more. If some of your readers do not meet all of the prerequisites you've set out for your book then it is their responsibility to gain those skills before attempting to use your book.

In some cases, your intended audience will not be so clearly defined. Parts of your book may include overview information while other parts delve deep into the inner workings of your product. In these cases you'll need to work particularly hard to develop a list of things and terminology all of your readers will understand, and perhaps divide your book into several sections for analysis. Just be sure to clearly state who each section is intended for within your introductory material.