Documentation horror

One of my first tasks at my new job was to install the company's software. The installation included setting up the database and application over several different servers in a cluster configuration. Installing software can be a good way to get acquainted with a company's product. It can also reveal weak points in the installation and configuration process. Unlike the inexperienced, veteran employees know how to install a product with their eyes closed, automatically smoothing out the wrinkles without even realizing it. Little did I know, as a freshman installing for the first time, I was poised to expose the problems in the procedure.

To perform my duty, I opened the appropriate manual and started setting up the database step by documented step. I got help from a fellow worker with the more esoteric parts, but got through it. I opened another manual and started installing the application. Before long, I stumbled upon a problem caused by a bad database installation. Apparently, I hadn't configured a variable in one of the database scripts. Why? Because it wasn't documented, of course. So I started over and set up the database from scratch. You can imagine my horror when, during the application setup, I got the same problem again. I had configured the variable, but incorrectly. Between my two attempts at installing, the format of that variable was changed and nobody updated the manual! I wasted over two days on something that should have taken a couple of hours because of bad documentation. There is a happy ending to this story, though: I finally got through the installation successfully on the third try.

The moral of the story is each and every document needs a parent. Documentation is essential in software. Nobody will remember a procedure or a design a month later, or even the next day. But it isn't enough to write the documents, they must be maintained. Once someone is responsible for it, the document is less likely to be neglected.