[lucumo]

To be fair, if the documentation isn't meeting the users' needs it is poor documentation.

One of my more tongue-in-cheek maxims is that too much documentation is worse than too little. With too much documentation the information might be there, but you aren't able to find it. The outcome is the same, but with too much documentation you've just wasted an hour failing.

It's slightly tongue-in-cheek because you can push the amount of documentation pretty far, but you have to think about how to organise it and how users will get the required information when and if they need it.

[dspillett]

> if the documentation isn't meeting the users' needs it is poor documentation

Unless they are not reading it, or properly paying attention. Or following an unofficial document and blaming the core project for failings in that. Sometimes it is on the user.

> With too much documentation the information might be there, but you aren't able to find it.

It can also became a huge burden to maintain, meaning it is in danger of becoming out of date or inconsistent.

[lucumo]

> Unless they are not reading it, or properly paying attention. [...] Sometimes it is on the user.

If they make no effort, sure. But looking for an answer to a question and finding something that seems to works is a perfectly reasonable way to use documentation. If there's a dangerous gotcha and it isn't documented right there, then the documentation is structured badly.

> Or following an unofficial document

That could be a very clear symptom of bad documentation.

Sometimes it's on the user, but if lots of users are failing to use your documentation, maybe consider that the documentation is bad.

[resonious]

I do agree with this in the end. I also think people often underestimate how challenging it is to create good docs.

I've seen this pattern often:

- Person doesn't know how to do something.

- They fumble around until they get it working.

- Once it's finally working, they write a doc about how they did it (because our "poor documentation" is a common pain point and therefore a popular problem to attack).

- If you actually search our internal docs, you find at least one other doc describing the same process.

I've seen this happen in many different contexts, even onboarding. I've seen multiple people join the company, and each one wrote down their own "onboarding painpoints" doc to hopefully help the next person, without even noticing the existence of the previous person's equivalent doc.

So again, I still agree with you. Even in these scenarios I described, I'm willing to believe that there is some way we could've structured our docs that couldn't prevented these issues. But I have no idea what it is, and seeing all the futile attempts at improving the situation makes me irk a little at armchair "poor docs"-style comments (not that that's even related. I've gone a little off topic here!)

[codetrotter]

LLMs augumented with RAG has great potential for docs as well.

Have a problem, ask the LL and it will reference the docs. So you don’t have to read through 40 pages just to find an answer.

Some products already make use of it for their docs. More will in the future.

The advantage then is that you can have up to date docs that the LLM can pull from and be able to hopefully accurately pinpoint relevant docs and summarize an answer for the user.

I also think some startups will come that focus on providing this kind of service. Probably several such startups exist already even. Similar to how there are some companies from before LLMs existed that focused purely on better access to docs of open source products.