The Code Documentation Fallacy
My problem with code documentation is that documentation is done at the function or class level.  When I'm looking at new code I would prefer a "concept of operations" describing how the whole thing works together rather than piecemeal function documentation.<p>This is especially important with open source code.  I'm not going to donate my time to working with an existing codebase if it is going to take hours to figure out how it all pieces together.  Examples are fine but what I really need to know is the why.  At least when I put up with this at work I'm getting paid by the hour.