[sourcedemand]

> The source code satisfies this demand.

If it's available...

Also, it's much harder to parse multiple files than one doc. Been there, done that, aplenty. Yes, I can find the answer, but that isn't sufficiently going to make it easier. Plus, if one admits the docs are bad because "the source answers that type of in-depth question", then are the docs not still bad?

[cjfd]

Sure, if the docs are bad, the docs are bad ;-). Jokes aside, though, I think the nice thing that this article does is pointing out various common ways in which the docs can be bad. My 'favorite' one is having docstrings for documentation. They take quite a bit of time to write, clutter the code with helpful information like 'the method get_heigth, gets the height' and if they are the only thing that is shipped as information use users severely lacking.

Another thing to note is that what this article lists as good docs actually cost a lot of time to create. Perhaps this is why people settle for the less than helpful alternatives. I think, though, that it is better to provide a subset of the good docs rather than useless docs that just annoy people.