by Jay Johansen | Feb 10, 2009
I've written a number of users guides for software products, and I've read plenty more. I've written a book on database design, and I've read plenty of "instructional" or "educational" books on a variety of subjects. And over the years I've noticed something interesting. I get the distinct impression that authors approach instructional writing with one of two very different motives.
Some authors are apparently are writing with the goal of making the subject as understandable to the reader as they can. They use simple words and sentences. They give clear, thorough, explanations. They give examples. Sometimes they try to help the reader remember important points by illustrating them with an amusing little story or a cartoon. They present material in a clear progression, starting from the easiest and building up to the most difficult.
Other authors appear to be writing with the goal of impressing the reader with how smart the author must be to understand this difficult subject. They use long, unfamiliar words and complex sentences. Examples are unnecessarily complex and convoluted. Everything is presented with deadly seriousness. They leap right in to the most difficult material without giving the reader any background to help him understand it.
Just look at the language used in instructional writing. Why do some authors say "use" while others say "utilize"? Or some say "idea" while others say "paradigm"? Maybe in some small number of cases there is actually some important subtlety in meaning conveyed by the longer word, but most of the time, the writer is just using big words to impress us.
When I write technical material as part of a team, I routinely find that my efforts to make it simple and easy to understand are met with stiff resistance. Someone will always edit it to replace short words with long words, to make examples more complex, and, at all costs, to cut out anything that could resemble humor.
At one government agency where I was a consultant, at a meeting one of the employees commented about how great the user manual for a certain software product that we had recently bought was: It used simple language, was easy to read, and used witty remarks to emphasize important points. Several other people at the meeting agreed that this was an excellent user manual, one of the easiest to read they had ever come across. So I suggested that we borrow some of these techniques in the user manuals that we wrote, that we use simple language and toss in some jokes and so on. Everyone immediately objected. "That would be unprofessional," one person said. "It wouldn't give the right image," another explained. I pointed out that they had all just praised a book that did just this. Of course their reply was, "That's different." Why? It just was. The unstated, underlying reason surely was, When I read a technical manual, I want it to be easy to read and understand. But when I write a technical manual, the goal is that it sound authoritative and pretentious. That is, I am writing to impress, not to inform.
Sometimes I walk away from an instructional book thinking, "Wow, this material is so difficult, I don't think I'll ever understand it. That author must be a genius to understand this difficult subject." Is that because I'm not smart enough to understand this subject? Or is it because the author did a poor job of explaining? On the other hand, surely the best instructional book is one that has you walking away thinking, "Well, that was easy. I don't know why I even bothered to buy a book to explain it, it's all so simple and obvious."
© 2009 by Jay Johansen