Documentation is a bit like people dying.
William Belk

I disagree. There is a wise saying, “if you can’t explain yourself, you don’t understand.” Even for the brightest of people, the process of documentation helps consolidate their actions, and also let their inner critic question their motives. After the process you will find that their minds are clearer, and more confident on their own work.

Yes, to a gungho developer documentation seems to be a nuisance, but often is case that when the developer finds out a major design flaw, the code might have gone a bit too far to warrant any effective solution other than workarounds. Having to throttle the developer’s brain through rigorous questioning (i.e., documentation) definitely mitigates this risk.

However, what I find counterproductive is excessive documentation. I remembered, as an intern, I once wrote a test code (yes, non-production code) for creating test images for CT scaners. It was about 8 kb with comments. My boss thought there was not enough documentation (comments) and started doing it himself directly on my code. This documented version ended up being 240 kb, while not a single line of code was changed. He even spent a whole page explaining how a 3-by-3 Gaussian elimination was implemented.

I guess there is such a thing as too much documentation.