October 24, 2003

Documentation

I love documentation. I like writing it, and when it's well written, I love reading it. There are many types of documentation, and they aren't all the same. Some serves to illustrate what you can do with a product (think the little product manuals that everyone throws away). Some serves to nail down exactly what will be done (in software, between two business parties, etc). But what I'm writing about today is software documentation, especially programmer to programmer documentation.

I love it for a number of reasons. Good documentation cuts down on communication between software engineers, hence increasing scalability. At the company where I used to work, each developer had their own instance of the application server to which we were developing (whether it was ATG Dynamo, Weblogic, or Tomcat). So, every time a new developer rolled on to the project, they had to be set up. Either the programmer had to do it, or someone else did. On a couple of the projects, I was involved in setting up the first one or two, but I quickly tired of that. So, I wrote a step by step document that enabled the incoming programmer to do the setup themselves. This was good for me, because it saved me time, good for the programmer as it gave them a greater understanding of the platform on which they were developing, and good for the project, as if I got hit by a bus, the knowledge of how to set up a server wasn't lost.

Good documentation also has come to my rescue more than once, by saving information that I struggled to find at one time, but did't not use every day. For example, I imported a project I'm working on into Eclipse. It wasn't strenuous, but it wasn't a cakewalk either. So, for other programmers on the project, I wrote down how I did it. Now, a few months later, I couldn't tell you how I did it. Not at all--that knowledge has been forced out of my brain by other more important stuff--like when my parents' birthday's are, what I'm going to bring to my potluck tonight, the name of that game where you roll plastic pigs around and score points based on their position--you know, important stuff. But, should I have a need to do another import, I can! I know the knowledge is stored somewhere safe (in CVS, but that's a different entry).

There are two complaints about programmer to programmer documentation that I'd like to address. One is that it quickly becomes outdated. This is true. It takes an effort to maintain documentation. When I change the procedure or meaning of something, I try to remind myself of the two benefits above. If I can convince myself that I will save more time in the long run by documenting (through not having to explain the changes to others or myself), then I do it. I'm not always successful, I'll admit. And you can see this with product documentation (both closed and open source). Out of date documentation can be very frustrating, and I'm not sure whether it's better dealt with by tossing the documentation or by keeping it and marking it 'OUT OF DATE.'

The other issue is what I call the 'protecting your job' excuse for avoiding documentation. If you don't document what you've done, you probably will have a secure job--especially if it's an important piece of work. But that security is also a chain that binds. In addition to being a subtle gesture of distrust towards your management (always a good idea to torque off your management in this time of uncertainty), it means that when a different, and possibly better, opportunity comes along, you won't be able to take it. Since no one else knows how to do your job (because teaching someone also is a form of documenting) you're stuck in the same position. Not exactly good for your personal growth, eh?

In short, documentation that gets used is good documentation, and well worth the effort to write.

Posted by moore at October 24, 2003 10:36 AM
Comments
© Moore Consulting, 2003-2006