Lesson 2: The Importance of Audience
What happens if your audience analysis is wrong?
Many of you probably didn't understand what all of the Visual Basic terminology I used in the last section means. That's because, most likely, you aren't Visual Basic developers. You weren't the intended audience described in that example, so you didn't have to understand what I expected Visual Basic programmers to understand.
However, since you are the intended audience for this class and knowledge of Visual Basic programming is not a prerequisite, I should have defined those terms, or used more generic language to describe similar concepts. Because I didn't I left many of you scratching your heads wondering what I was talking about. This is bad.
Your initial audience evaluation may be wrong for a number of reasons or, as in the case of the example above, there might be two audiences which have different backgrounds and knowledge bases. The best you can do is clearly define an audience and clearly state, up front, who you are writing for. In some cases, you may be given two audiences with very different requirements. For instance, you might be told that in addition to teaching those Visual Basic programmers what they need to know to write those front end applications, a particular chapter of your book will also be available as a sample to potential customers so they can evaluate the quality of the documentation. In that case, you need to keep both audiences in mind and, to some extent, write to the lowest common denominator.
Even if there's only one audience you can still make mistakes. You might not have understood what the product does well enough to competently evaluate its intended audience. The product can change significantly after your initial interaction with it. Sometimes the overall documentation plan changes and you're stuck with a different focus than you were originally assigned. For instance, going back to our example, although originally you were supposed to write separate guides for writing front end applications in Visual Basic and in Java, the powers that be decided two months into your project to combine the two books. You've already written half of the Visual Basic book assuming everyone who reads it will know Visual Basic. Now it's your job to go back and determine what people who write front end applications in either Visual Basic or Java have in common and which items you'll need to explain better because only one group will recognize the terminology you used or because a specific concept exists in Java but not Visual Basic.
Your conversations with the product manager, with other people working on other books for your product (assuming there are others), with developers who are writing the software, and with testers and other internal personnel trying to use the product will help you hone in on places where you don't write to the correct audience. Hopefully all lapses or changes of focus will be caught before your manual is actually read by real users.
