Software Documentation

When Brian Marick had a problem with CruiseControl he rejected 'use the source Luke' because he didn't have time. This makes an interesting implicit point about software documentation; often you are too busy to use the source. If someone has provided a framework which you are going to utilise then it needs to be documented since you are always too busy. You may respond with "that's ok, that only applies to stuff like Spring, Ant, Cruise and the rest since they are tools or frameworks and designed to be treated as a black box". The 'black box' is a consequence of abstraction, and all s/w should utilise abstraction where needed to control complexity. If we follow the 'no time' argument to its end then this implies there needs to be some degree of s/w documentation for key abstractions within a s/w construction (key == (stuff we use a lot || hard stuff we use little enough we forget it)).

I think it is this that gets my goat when I'm reading code with no decent comments or class responsibilities. I know that there is no guarantee that comments are kept up-to-date, but the question in my mind is 'should we avoid using things because they not be reliable or make sure these things become reliable'? I'd prefer the latter, though its harder and if there is a solution its probably self-discipline.