The Source of Bad Writing: Don’t Let It Be You

Stephen Pinker, publicizing his book The Sense of Style, kicked up a fuss with his piece “The Source of Bad Writing,” which appeared in the Wall Street Journal last September. He began:

Why is so much writing so bad? Why is it so hard to understand a government form, or an academic article or the instructions for setting up a wireless home network?

The most popular explanation is that opaque prose is a deliberate choice. Bureaucrats insist on gibberish to cover their anatomy. Plaid-clad tech writers get their revenge on the jocks who kicked sand in their faces and the girls who turned them down for dates. Pseudo-intellectuals spout obscure verbiage to hide the fact that they have nothing to say, hoping to bamboozle their audiences with highfalutin gobbledygook.

I resent that remark! I haven’t worn plaid since high school. And we don’t write obscurely to get back at anyone, we write obscurely because we don’t understand what we’re given. But looking past his gratuitous dig at us, Pinker offers the valuable nugget that knowledge itself causes cognitive blindness:

The curse of knowledge is the single best explanation of why good people write bad prose. It simply doesn’t occur to the writer that her readers don’t know what she knows—that they haven’t mastered the argot of her guild, can’t divine the missing steps that seem too obvious to mention, have no way to visualize a scene that to her is as clear as day. And so the writer doesn’t bother to explain the jargon, or spell out the logic, or supply the necessary detail.

Subject-matter experts endemically suffer from this malady. But we can fall victim to it as well, not at first but over time. And sometimes we are carriers. Here’s what I think.

When we start a new project, our lack of knowledge lets us put ourselves in our customers’ shoes, and we clearly see what has to be said. But as we learn more, we lose that advantage. Forgetting to include prerequisite knowledge or steps can make a procedure unusable. At Digital Equipment Corporation, a colleague recounted observing outside a testing lab as volunteers attempted to install printers using his instructions, and wanting to go through the glass to tell them what they were doing wrong. Another company employed a great product manager who was the worst technical trainer I ever saw. He was highly intelligent, knowledgable, experienced, and glib, but he didn’t realize how his knowledge made him a liability in the classroom. Our product was an extremely complex integrated development environment, and I for one never understood the fundamental question of how you decided what piece of code to use to solve a business problem. Neither did our customers. But when they asked him, he would respond, “Well, think about it!” He made customers feel both ignorant and stupid.

To expand on one of Pinker’s examples, I have set up and troubleshot a wireless home network. One configurable router value is NAT filtering, which on my NETGEAR router can be set to Secured or Open. As a user, I naturally wonder: what is it? Why would you secure it, and what happens if you open it? What problems would make you want to change the value? How would you know if it was set incorrectly? The router has a web interface and displays online help for each configuration page, and does a good job explaining the available options: “This option determines how the router deals with inbound traffic. The Secured option provides a secured firewall to protect the PCs on LAN from attacks from the Internet, but it may cause some Internet games, point-to-point applications, or multimedia applications not to work. The Open option, on the other hand, provides a much less secured firewall, while it allows almost all Internet applications to work.” This tells me what my choices are, but doesn’t actually say what NAT is. A Cisco document dedicated to NAT translation, available on the Web, starts with a definition and then continues: “NAT enables private IP internetworks that use nonregistered IP addresses to connect to the Internet. NAT operates on a device, usually connecting two networks, and translates the private (not globally unique) addresses in the internal network into legal addresses before packets are forwarded onto another network. NAT can be configured to advertise to the outside world only one address for the entire network. This ability provides additional security by effectively hiding the entire internal network behind that one address. NAT is also used at the enterprise edge to allow internal users access to the Internet and to allow Internet access to internal devices such as mail servers.” Between the two of them, my questions are answered.

But sometimes it’s not that we learn too much, it’s that we never know. For example, the documentation of forms tends to focus on the mechanics of using the interface, which we understand and can tackle. But what goes in the form fields, and why? Engineers tend to scoff at the idea of providing field information, invariably going to the “are you going to write how to fill in the ‘First Name’ field?” example. But take an example from my current domain. Can you tell me which AVP in an incoming Diameter message to key on? No? Well, think about it: all the supported AVPs are in the drop-down list, and you just have to pick the right one. What’s so hard about that? Oh, I can tell you that I’m talking about attribute-value pairs (information that is true but not helpful). And Diameter is a signaling protocol. And different devices encode different AVPs into Diameter messages. I can go on quite a ways without saying anything useful. (Sometimes I worry I do just that.)

The solution to this problem is to go ask, “what is this and why do I care?” It’s scary to open yourself up and say that you don’t understand something. Perhaps scarier, often the engineers themselves don’t know. A typical response to “what is this value and what does it do?” is “I don’t know, I was just asked to add the value to the list.”

As technical communicators, we are well-versed in the concept of audience analysis, but it never hurts to get a booster shot of naiveté now and again. If you’ve worked on a product for several years, congratulations, but maybe it’s also good to shift assignments once in a while. As soon as you open even a related product’s documentation, the logical holes jump out at you. And you see the problem clearly every time you buy a product for your own use and try to use the documentation. I just switched wireless carriers and got a new phone, and instantly I was transported to when I first got a cell phone and couldn’t figure out how to answer a call. (Actually, I was answering calls and cutting the callers off. My son, who was trying to reach me, could not have been amused.)

Last fall we were preparing for a major vacation, and we bought a Nikon COOLPIX digital camera. It reduced me to helplessness. The designers had overloaded the interface (that is, the few buttons did multiple things each). Even after reading the manual carefully, it took lots of fumbling and practice before I understood how it worked. (The camera has built-in on-display help, which I also consulted a few times.) In the end the camera worked beautifully and took some outstanding indoor and outdoor photos, videos, panoramas, and food close-ups. I think I used every setting except “pet portrait”(!). But I succeeded only because I used the documentation—had I just picked up the camera and tried to use it, I never would have found half the things it could do, and we would have wasted a lot of money and missed some unforgettable shots. Fortunately, the documentation was effective (and the graphics were excellent).

So I guess my vacation was a shot in the arm in more ways than one. It’s good to wipe the knowledge from your eyes every once in a while.