Documentation...(Un)Necessary Evil?!
I hate writing documentation. Loathe it like I loathe Oprah (need a seperate post for all the ranting involved in that one…). But it is necessary. Writing a piece of software without documentation is like having a movie that is just the ending. How’d you get to this point? Where do I start? How did all this come about? Why are you doing this?
Documentation aims to answer all these questions for your fellow developers, especially in a team environment. Asking someone to extend a feature for an application you’ve written without providing them some kind of documentation should be considered a felony in the state I work in. There are legacy C++ and FORTRAN programs that I have to maintain that have ZERO documentation. No comments, not even a little readme.txt file that says “Hey, sorry I’m lazy…umm, I decided to write this code before you were born (not kidding on that one…I had to update a piece of FORTRAN code a month ago that is 10 YEARS OLDER THAN ME!!!) and it does something…you figure it out. And fix it. And…yea, good luck!”
I’m in the middle of writing some design documents for a rather large system that has been actively developed over the past 2 years. I have been on the project for the duration of this time, and am just now getting together some of these documents. I have taken with me a crucial lesson: write your documentation as you develop, or you will be in for a world of hurt for a few weeks/months. As a developer, I love coding. Love it. Writing is OK, except when it’s describing the software I’ve developed. Then it becomes a chore in my mind and I get really bored really fast and want to jump back on developing something new. I find it really hard to stay on task for more than a half an hour at a time before I start hoping a service request comes in or a quick fix is needed somewhere. Anything to distract from writing documentation.
But then I get really angry when I look at code that has ZERO documentation. Hypocritical? Oh yes. Very.
I’ve decided I need to start being a lot more proactive in my documentation efforts as I am in the development process, instead of waiting until the end and fighting through writing 100+ pages of dribble that is of no interest to me. By doing the work a little at a time, my hope is my pseudo-ADD won’t rear it’s ugly head taunt me with the impending doom that “documentation” has done to me in the past.
Sorry, back to your regularly scheduled programming…