Analysis Paralysis

Taking what you learned about generated documentation, it might be tempting to turn the controls the other way round. If documentation with zero input effort doesn't provide much additional value, then maybe the more you increase the effort spent on creating documentation, the more useful it becomes.

Perhaps, to a point, this is true. However, the incremental value of adding documentation is asymptotic. In fact, no – it's worse than that. Create too much documentation and people can't even work out how to use that without some guide – some meta-documentation. Shovel too much in and it becomes harder to use the docs than if they didn't exist at all.

Notice that analysis paralysis (http://c2.com/cgi/wiki?AnalysisParalysis) isn't directly related to writing documentation; it's actually a flawed design methods. The interaction with docs comes when you dig into the problem. Analysis paralysis occurs when you're afraid to move away...