
Don’t Trust Documentation — Ever - twampss
http://www.cimgf.com/2009/03/23/dont-trust-documentation-ever/
======
mpk
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).

------
jwilliams
This is totally summed up by the conclusion: " _I am sure many will object to
my verbage in this article. Some may find it offensive. It should be. It was
intended to shock._ "

