[cjfd]

The article is quite a bit smarter (if a bit long) than this comment. "The first duty of your documentation is to be complete and correct". The source code satisfies this demand. It is complete and it truly describes the product in all its details. But now we are stuck in 'act 1' of the article. So maybe we need some more helpful hints. O wait, there is an article called 'Teach, Don't Tell' that provides these helpful hints.

[mjw1007]

The bad documentation I come across often shows every sign of having taken the advice from this article (and others like it) to heart.

The trouble is that the advice doesn't include ways to make sure your documentation actually covers everything it has to.

What this article says is that you should have « "API documentation" for every user-facing part of your project. »

That commonly leads to "reference" pages which are very little better than the autogenerated documentation the author dismisses. The main problems tend to be that behaviour that isn't controlled by a specific command or function or configuration setting doesn't get documented at all, and that commands with complex behaviour get described using terms that themselves need further definition which isn't provided anywhere.

[AlienRobot]

My experience is that the main problem with online documentation is that it doesn't include links to separate tutorials, but has plenty of links to more documentation, leading you to wander from page to page without destination trying to find that one page that actually explains what you're trying to do or infer it from fragments of information scattered around the documentation.

For example, in Qt you have a view class, a model class, and a selection model class, and none of their pages tell you how to actually select something programmatically. You have to guess or ask ChatGPT these days.

[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.