Good Documentation Delivers Value

I’ve written a fair amount of poor documentation in my life, but one experience eclipses them all.

I was an engineering intern, doing research and development on high performance X-ray tubes. One day my mentor asked me to document an internal process and get it back to him for review. He had industry experience and a PHD while I was an undergraduate nobody, desperately trying to preserve some degree of competence in an environment that was constantly exposing my ignorance.

I worked hard on my draft and felt good about it when I turned it in. He returned it a couple days later along with a copy of “Writing for Scientists and Engineers. He said, and this is almost an exact quote: “Can you give it another try? I don’t understand what you’re saying.”

I was dumbfounded.

He explained that my document had too much jargon. Too many long sentences and long words. It was exactly the kind of documentation nobody wanted to read.

The funny thing is, I had tried really hard to make it read like that. It looked like other internal documents at that company and it looked like every textbook, dissertation, or peer-reviewed journal article I had ever read in school. All “professional” writing in my field was heavily technical. That’s was just how you were supposed to do it… or so I assumed.

I didn’t like reading overly-technical textbooks, but I figured that was my own problem. Once I learned more and became a professional, maybe then I’d appreciate it. Right?

Well, news flash, I got my degree, became a “professional” and I still hate reading overly-technical writing. So does everybody else.

So why are we writing heavily technical documents that nobody wants to read?

I believe it is a byproduct of acute myopia. We’re writing for ourselves. Not the reader.

When professors write textbooks, they have something to prove. They want to show that they are an authority on the subject. They want to show that they know all the appropriate terminology. But really, they’re just older (and balder) versions of the students writing essays in their class. I was constantly trying to use big words and sound smart as a student. The alternative was B’s and C’s. Everybody’s trying to show everybody that they know their stuff.

But when I write documentation for people in The Real World™, they don’t care how smart I am. They have a specific need, and that is to get some specific piece of information. If me trying to sound smart gets in the way of them finding the information they are looking for, there’s a Back button, and another Google search result calling their name.

And this is how it should be. I’m not delivering value to anybody by making myself sound smart. Good documentation delivers value.

(And, by the way, delivering value makes you look a lot smarter than writing opaque documentation)