Knowing Your Audience
A natural human behavior is assuming that the majority of the world’s people are similar to us; similar in thoughts, assumptions, knowledge, opinions etc.
Psychologists may see this as the consensus effect, a form of cognitive bias. If you love ballet, you likely assume that far more people also like it than actually do.
What does this have to do with documentation?
When creating the various types of documentation, it is important to know your audience and understand their comprehension of the topic. In many cases, things that are second nature to you will be completely foreign to the majority of the world.
If you are reading this, chances are you know what https means, but there are many people who only know that it sometimes goes in front of a web address, if they even know that.
For general distribution documentation, including company-wide policies, you generally want to stay around a fifth grade reading level. (If you want to know why, fire up your favorite search engine and enter “reading comprehension levels of college graduates.”)
Of course, nothing is ever that easy, because on the other side of the coin you want to make sure that you aren’t talking down to certain audiences. If you are creating a highly technical specification to be used solely by engineers, you can leave out the explanations of basic math.
Also keep in mind that the same word or abbreviation can have multiple meaning to multiple audiences. DC? To tech folks, that is the datacenter. If you work in a warehouse, it is the distribution center. Electricians will take it as Direct Current.
To generation Y, DC is a shoe company, and to their parents it is a comic book company. DC is also shorthand for the District of Columbia. The list could go on and on, and that is just one example. So be certain to explain any abbreviations or acronyms the first time you use them within each document.
We must also consider not just denotation, but also connotation, especially in view of the vast range of connotations a general audience may have. The right amount of detail is essential. This becomes even more important when users may not be native speakers of English.
Writing to the correct audience is one of the most important elements of creating effective documentation. If the documentation is too technical for the audience, they will not understand it and likely not read it. Conversely, if the documentation is too simple for the audience, they may skim over important points.
In the next installment, we will discuss some of the intricacies of language. Should you read it, or must you read it?
Cross-posted from SecureState Blog