Documentation: The Neverending Battle

Over the years at Dr. Dobb's, I have slowly developed a system, written mostly in Perl, for extracting the content of articles from the print Dr. Dobb's Journal and tagging it as HTML. I must confess it's a monstrous tangle of spaghetti code. But that's not my biggest sin. My biggest sin is documentation, or specifically the lack of it.

I'm not talking about end-user documentation. I actually tackled that problem a couple years ago. Of course, what I produced in that effort was a tome so large that the only conclusion that I could come to was that my system was hopelessly complex. No, what I'm talking about is documentation for me.

Because it's a Frankenstein of Perl, Applescript and Mac and Unix applications, installing this beast is not a job I have been able to interest anyone else in doing. But you'd think I'd learn to make a list of the various dependencies, and give myself a written procedure to make the process go more smoothly.

Nah. That wouldn't be any fun. Then I wouldn't have the suspense and drama of double-clicking and wondering if I forgot something while I wait for some missing Perl module or scripting addition to cause the app to barf all over my screen.

Of course, I always manage to get it running. But that's only because I've been staring at the code for this system so long that it has copied itself into my DNA. This isn't ideal, obviously. I'm one of those disorganized programmers who keeps too much in his head, and not enough on paper. The obvious end result of that is that I make the same mistakes over and over again. The less obvious result is that I deprive myself of an opportunity to critically examine my creation when I don't write things down.

And that, I suppose, is the real point I'm trying to make: Documentation shouldn't be just a chore at the end of the development process. Start it early and update it often. Flaws in your program you didn't even know existed will come into focus if you are continually forced to put into words the exact procedure that must be followed to use your app.

Posted by Kevin Carlson at 01:13 PM  Permalink

This is a public forum. CMP Media and its affiliates are not responsible for and do not control what is posted herein. CMP Media makes no warranties or guarantees concerning any advice dispensed by its staff members or readers.

Community standards in this comment area do not permit hate language, excessive profanity, or other patently offensive language. Please be aware that all information posted to this comment area becomes the property of CMP Media LLC and may be edited and republished in print or electronic format as outlined in CMP Media's Terms of Service.

Important Note: This comment area is NOT intended for commercial messages or solicitations of business.