On the apparent false economy of written documentation
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.