Hypothesis: programmers over-use the word "documentation".
It has come to mean "prose about computer programs" and is thus so general as to be useless.
Programmers discuss whether it is good to document code or bad to document code, whether or not we should even consider a product to be usable if it doesn't have documentation, whether tests are documentation and so on. It's all a colossal waste of time.
Part of the secret is that no one ever sits down and thinks, "I'll make myself a nice big cup of tea and curl up by the fire to read some documentation, just for the sheer joy of the thing".
People don't read documentation for its own sake, they read documentation because it is necessary to do something else that they care about. (Likewise they don't use your software for its sake).
When I was a lad, video games used to come with instruction manuals. I'd read the manual while my brother started playing the game. Frequently I'd be able to help him because the manual contained some clue or trick that wasn't obvious in the game.
Nowadays, video game manuals contain nothing but health and safety warnings. The game itself teaches you how to play.
Do we complain about the lack of documentation?
When we complain about the lack of documentation, what do we really mean?
We might mean that we don't understand what a thing is actually for, and when we looked for an answer we couldn't find one.
We might mean that we couldn't understand how to use a thing.
We do not mean that we wish we could spend more time reading about that thing.
When we complain about the lack of comments, what do we really mean?
We might mean that we don't understand what the code is there for.
We might mean that we don't understand what the code is doing, or that it took us a long time to do so.
We might mean that we don't understand why the code is written in this particular way, rather than some ostensibly simpler way we have in our heads.
A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.
Documentation Thought Experiment: imagine the user manual is named "Handbook of Being Badass With This" then make it so.
If you are working on documentation and you haven't written down who it is for and why they are reading it and what they ought to get out of it, then you are wasting your time.
I am not against documentation. What I want to do is emphasize that the slap-dash way we apply the word often masks our mental fuzziness on deeper, more important issues: audience; purpose; outcomes.
Writing something out is an immensely valuable mental exercise. I find it clarifies thought, reveals areas of ignorance, and exposes assumptions.
But writing something for someone else? For a total stranger? That is both much more work and a very different kind of work.
Imagine a kind of documentation that appeared exactly when it was needed, and that could take the user's current context into account.
What could we do with such documentation? How good we make it?
This form of documentation exists today. We call it "error messages".