Rants, rambles, news and notes from another geek

Documentation, Documentation, Documentation

Wallace McClure has been writing about his unhappy experiences on a new project. In one post he wrote:

I asked for some documentation when I first got here.├é I looked at it, realized that this was some “God-n-Country” documentation that basically was a cut-n-paste of some Microsoft Marketing documentation for├é certain technologies,├é and then asked for the programming documentation.├é There is no programming documenation and the guys that originally developed this app have left.

My question to Wallace and everyone else out there is this:

Have you ever walked on to a legacy project and been given good documentation?

I haven’t. I don’t know anyone who has. I’m not saying “no documentation” is a good thing, but I think people have a tendency to yell “WHERE ARE THE DOCS?” anytime they have to take over someone else’s code. The fact is, taking over someone else’s code sucks. No one writes code and cleanly as you do, and everyone makes decisions that you wouldn’t have made.


Even if you have been handed a bible of documentation, did you trust it? Did you just end up reading the code anyway? I’ve certainly heard this before: “Yeah, that (points to binder on desk) is the docs from the last release but they seem to be way out of date, so I’m just reading the code.”

I don’t like this anymore than you do, but I happen to agree with the TDD guys who preach that the code itself is the best documentation. If it is well written and clear, you shouldn’t need much more than a few pages of architectural and glossary information. Maybe not even that.