Writing isn't about impressing people. It's about sharing what you know via the spoken or printed word.
Technicalities and acronyms are a great way to telegraph ideas when you are talking to a peer, but rattling them off in blinding machine gun succession to outsiders just leaves the recipients stunned. Use unexplained, obscure, and complex words and you might as well be writing in Greek. Even when communicating to those who know a good deal about a subject, it is unwise to cram too many technical terms together. Indigestible passages invariably go in one ear and out the other.
Making a sentence interminable is another way to switch off readers. An average of 11 words per sentence is about as much as the average person can absorb. The best advice is to keep it simple. Write in Universal English. The best tips are those that experts have been giving for years:
♦ Keep sentences short.
♦ Favor short punchy Anglo-Saxon words.
♦ Select words that conjure up pictures.
♦ Throw out adjectives.
♦ Concentrate on verbs.
♦ Use technical words sparingly.
♦ Spell acronyms out the first time you use them.
Professional trainers recognize four principal modes in which we assimilate information:
♦ A few divine what the author will say from his or her opening sentence and run off immediately to try and test it.
♦ Most readers absorb information in small chunks and test things out in tentative steps.
♦ Some of them absorb whole subsections before they start to apply what's being said.
♦ One or two never make a move until the very last item of information drops into place.
Explaining software, however, is a linear activity. You can't do B until you have done A, and you won't understand B until A has been explained. So, if you don't explain everything clearly as you go and define every new term when you mention it first, your readers will get muddled and frustrated.
Successful documentation writers spend a lot of time thinking about their readers. Whenever they put finger to keyboard, they always have them in mind. What do they want to know? Are they looking for a brief or full answer here? What is the best way to get this across? Will they all understand that word? Am I being too simple? Trite as these examples may seem, they will give you an idea of the way you might create your own set of yardsticks. Also remember that every audience is composed of very different individuals. Not only do readers absorb information at different rates, but men think differently than women, adults think differently than children, and new users process differently than experienced hands.
For example, this book is aimed at computer professionals, business people, and students. So I have three imaginary friends looking over my shoulder as I write.
Before you start on any documentation, jot down the kinds of people you intend to address. Think about them in the following contexts:
♦ Educational levels
♦ Likely business experience
♦ Computer knowledge
♦ Energies and any special interests
♦ Prejudices and limitations
Then ask yourself what level of complexity could appeal to them all.
Was this article helpful?