If nobody reads documentation, it means they don't trust it.

Trust is something that documentation for a project has to earn over time.

People will assume the documentation is incomplete and out-of-date, because that's the default for most things.

If it's comprehensive and stays up-to-date with new changes, the project community will eventually come to realize they and start trusting it. But it takes time to build up that track record!

I think we also tend to teach people to not read documentation (or spend time learning anything, really).

Maybe there is some kind of negative reinforcement, too. The way it feels to me is: "I won't write documentation, because users don't read it -> Oh great, I will use ChatGPT to support my users -> The users don't know how to read documentation (or anything other than a 500-letters answer to a chat question) because they do everything with ChatGPT-like prompts -> I won't write documentation, because users don't read it".

Same for many things: most people tend to complain about CMake, but almost every time, I quickly realize that they don't know how to use CMake. Either they complain about it and never used it, or they complain and use it wrong. Therefore many devs try to build alternatives that will solve that problem by "being better than CMake". Turns out I have seen Meson projects that were a big mess, it's not just a CMake thing. On the other hand, people who learn how to use Autotool/CMake/Meson usually manage to make it quite maintainable.

Here the negative reinforcement would be: "People don't learn how to use the tools properly -> They make a mess -> They complain about the tool -> Someone makes a "better tool" -> People don't learn the new tool and make a mess -> repeat.

I truly believe that we could solve many problems by teaching people how to learn, instead of building technology that helps them being productive without learning.

CMake has a bit of a documentation problem, though. Firstly because the tool really was pretty bad at the start and the correct way to use it is the new way, but all the examples people run into in the wild are generally using it wrong, and this becomes self-perpetuating. The second issue is that the main documentation is actually really light on examples, it's just a fairly dry (and not always helpful) description of each part of it. I know there's some pretty good books but that isn't the kind of resource a lot of people are going to use when learning a tool, especially a tool they regard as secondary to their actual goal.

I totally agree that copy-pasting examples from random websites is a bad idea, because there is a very high likelihood that those examples use it wrong.

Regarding the CMake documentation, though, I have been relying on it forever (that's pretty much how I learned CMake), and I personally find it pretty good. That is where I believe there may be some kind of cultural change: I am fine reading the manual (`$ man <command>`) and RFCs and documentation like the CMake one. It feels like "the modern way" is to find an example that does what you need and mimic it (hence the success of stuff like Copilot).

I just feel like my way is more powerful: I can both leverage official documentation (and RFCs, etc) and examples, and I can actually use them together (e.g. read the example, see new stuff there, and go read the official docs about those new things). IMHO, only being able to rely on examples that do almost exactly what one needs is a bit of a loss; people should learn to read actual manuals.

Case in point: Arch Wiki

I don't think that they don't trust documentation. I think that they don't want to invest half or a full day reading the docs and learning every facet of the tool. They are in hurry and if they can find the right answer, discord, ChatGPT, whatever, that would do.

I read all the Unix man page of every command line program I used but there were only a few of them. There are a zillion of tools now, I can't spend days reading their docs: I won't be able to deliver to my customers and get paid. Googling how to do X magically works well enough.

Discord is the very last resort, only if desperate. I tend to keep very far away from tools that have discord as their primary documentation. There are always alternatives.

even if people ask the same question rather than looking for docs, it's still a huge timesaver to direct them to the documentation rather than re-explaining from scratch everytime. Plus, after having been shown the docs they _might_ now be aware that they exist and self-serve the next time

Plus it's an opportunity to fix the documentation. You will figure out quickly if a section of it is too confusing. It would also help you to realize if it's not easily discoverable.

Most servers have a bot that people use to store and retrieve common answers so contributors don't have to type it out every time.

Now you could be like clearly that should just be in the web documentation but people still show up and ask even when it is and RTFM isn't exactly nice.

1. Of course people read it.

2. People read the docs when you send them a link to the relevant doc page. Having docs makes your chat support a matter of linking to the right page.

I guess that's true. I also guess one should consider the fact that you could (as long as things don't change) "waste" your time writing the documentation once, and saved time accumulates, while "saving" your time today not writing documentation will accumulate time spent on answering questions over and over.

Saved time today VS saved time tomorrow, the constant question for startups :)

If nobody reads the documentation, that's an indication of success, not failure.

It means you've done a good job with the product and people don't need help to use it.

I find this prevalent attitude actually harmful. It is kinda weird thing to think that the tools we use should not need any learning or training, that anyone should just be able to pick them up and be productive.

Of course I understand it is reflective of the current situation where naturally it is not worth seeking expertise when software gets at minumum a redesign every six months if not thrown out completely. But I'd really question is that actually good situation to be in?

Yes, but don't confuse cause and effect.

That is one of the explanations but you should not dismiss the others.

People read the documentation and fails to understand it. Writing good clear documentation that successfully guides your users or customers to gain the most value from your product is incredibly hard.

It's fine to have Discord, or something similar, for when you users come to you with a problem, but then you need to consider if you have to go back at update the documentation. Early in my career hanging out on mailinglists was much more popular, frequently you'd ask a question and the maintainers of whatever software you where using would take the answer and put them into the regular FAQ or documentation. Now we replaced Discord with mailinglists and that might be sensible, the feedback loop just should not be excluded. Discord is terrible place to store knowledge.

If it's hard to write documentation that people will comprehend, doesn't that make it equally hard to write near real-time chat messages that people will understand?

Yes and no, but at least they'll be able to provide real-time feedback and you can tailor your response to they specific situation.

That is survivorship bias. You hear only from the customers who don't read it.

(I like writing documentation.)