The Apparent False Economy of Written Documentation

· 497 words · 3 minute read

Anyone who’s worked with me for more than four hours knows that when it comes to efficient use of time at the office, I have the soul of an 80-year-old curmudgeon. I take time to write up documentation with executive summaries, working hyperlinks, sample code, and FAQs, and in exchange I expect people to read it. But all too often the pattern goes like this:

Imminent Target Of Rage: Hey Mike, so I saw we have a new schema for brillig, and the slithy toves need to gyre and gimble in the wabe, and anyway, I saw you sent out something about how to do this…

Mike: Yep, the first FAQ entry I sent out has a cut-and-paste command-line to whiffle the vorpal sword, which gimbles the wabe.

Imminent Target Of Rage: Oh, OK. Command line. I uninstalled my shell when the mome raths outgrabe, so I could still use some help.

Mike, beginning to seethe: The first FAQ entry also refers to the second FAQ entry, which addresses engineers who prefer a GUI interface.

Direct Target Of Rage: Hmm, all right. So anyway, I think I actually deleted your email with the link to the FAQ.

Mike: We use Google Apps. Nobody at this company deletes email.

Direct Target Of Boiling Rage: (long pause) Can you help me gimble the wabe?

Granted, my recounting of this dialogue is one-sided. But there are some truths in it. Some people read documentation, some people work in a more verbal or visual fashion, and the two groups will not, by definition, be able to communicate with each other without either changing their style or finding a mediator. My usual approach in life has been to demand that others change their style, because (a) spoken communication is inefficient if it can be expressed clearly in writing, and (b) I don’t want to become the mediator.

For some reason, yesterday I let two neural paths in my mind cross. I was musing about public speaking and marveling at how much a difference good preparation makes, and I analogized it to my constant efforts at work to document every fact or skill worth sharing with my coworkers. If that documentation is like public-speaking prep work, then at the end of creating it, and at least for the next day or two until I forget what I wrote, I am almost certainly the most prepared person on Earth to present wabe gimbling or sword vorpaling. And if that’s the case, why not treat a coworker to the best damn presentation ever on that topic? Why stew about it?

I still need to quell the efficiency and public-policy demons that scream in my head as I write this. What about scaling the organization!?! What about encouraging a culture of independent productivity???!! There’s certainly a balance to be found. But I’ve spent a long time over on one end of the scale, and I’d like to try scooting over a bit toward the other side.