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, do not assume they understand database theory or any of the associated terminology. It sounds obvious, but the failure to properly analyze the 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, chances are you won’t be able to write documentation they will 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.
Discuss the user base with the product manager
It’s all well and good for you to determine just who your intended audience is, but if the majority of people actually using the product differ greatly from your vision then you need to adjust your plans. Another way to determine who will be using a particular product is to discuss how that product is being marketed. The product manager is usually responsible for setting the requirements and marketing direction for a product. He or she should be able to provide a 30,000-foot view of what the product does and who should be using it. In general, the product manager is in charge of the overall product that ships to users including the documentation. Although the chain of command may vary from company to company, you will most likely need the product manager to sign off on your documentation plans and on your final manuals.
You may find that the product manager has a vastly different view of what the product does than you do. Product managers usually work in the abstract; they’ll look at product specifications and the intended purpose of a product rather than what the developers actually made a product do when they built it. If you’ve based your vision on a working version of the product and it differs greatly from that of the product manager it is your responsibility to bring that discrepancy to his attention. Whenever possible, you should point out these discrepancies between plans and implementation to the developers and other interested parties as well as the product manager so that everyone understands precisely what is it the shipping product does regardless of intentions. Unless directly ordered not to do so, you should document what the product actually does rather than what it’s supposed to do.
Applying your audience analysis to your writing
You should keep your view of the intended audience in mind at all times throughout your design and writing stages. As you’re writing, think about what someone with that skill set and experience would already know about the topics you’re writing about. Consider whether they’ll be familiar with standard terminology or if you need to define every technical term you use. Organize your book in a way that will make sense to that audience. If you expect a particular book to be used as a reference, make sure each small piece of information is indexed and otherwise easy to find. If you’re writing a conceptual overview of a topic, make sure either your intended audience should already know the topics leading up to that one or that you’ve documented those other topics before this one.
Going back to our previous example of teaching Visual Basic developers how to build front end applications to our product, we know we can insert Visual Basic code into our documentation without much explanation, that we can assume the reader understands the concepts of data types, that the reader knows what forms are and how to move from one form to another, that they know how to create buttons, labels, and other controls, and that they understand how error handling works in Visual Basic. However, if our product makes various error messages available, I cannot assume the user knows these codes but I can assume they know how to implement them once I provide a list of codes and when they should be used.
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, upfront, 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.