I think it was Linus Torvalds who said 'Documentation is like sex. When it's good, it's really, really good and when it's bad it's better than nothing.' But ap

I think it was Linus Torvalds who said 'Documentation is like sex. When it's good, it's really, really good and when it's bad it's better than nothing.' But apart from stuff like javadocs (which usually is just type information and fairly relaiable but generally uninformative) any coder with a few years under their belt will just see documentation as signposts. Stuff that might, just might, get you part of the way there. Let's take Microsoft as an example. Everyone is always going on about how stellar their documentation is. And they're right. MS does documentation for established products really well. But if you happen to be interested in, say, the limits of the jscript library ... well, you're out of luck. It becomes a hole and you have to resort to black box techniques or reverse engineering to figure out what those limits are. Also, software documentation has its own scale. Where do you put all the documentation you're supposed to be writing about your codebase? Some of that is easy ('document a method') but as you move up the abstraction scale you end up with tutorials, which obviously have no place in source code. Where do you draw the line and how do you manage to keep the documentation outside of the source in sync with the source? And while we're on it, changes in source will have to be kept in sync with documentation about it that exists somewhere in the codebase. (All of this is no excuse for not actually having good documentation, btw).