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
prada shoes Sep 15, 2017
oakley sunglasses Sep 20, 2017
I wish to show appreciation to this writer just for bailing me out of this trouble. As a result of exploring through the online world and seeing notions that were not powerful, I thought my entire life was gone. Living devoid of the approaches to the issues you've fixed by way of your entire posting is a critical case, and the kind that would have badly affected my career if I hadn't encountered your web blog. Your personal skills and kindness in taking care of every part was precious. I'm not sure what I would've done if I hadn't come across such a point like this. I can at this time look ahead to my future. Thanks a lot so much for this high quality and amazing guide. I will not think twice to recommend your blog post to any person who should have tips about this subject.
replica rolex Sep 22, 2017