> good sign your documentation has some challenges: dense; intimidating; inaccessible; or not easy to search for the specific information you want

Of course it does. And it’s not “my documentation” it’s ours. And everyone is responsible for improving it. It’s not about pointing out that documentation sucks, it’s about working to improve it.

I don’t have a documentarian on my team. No one’s main job is to write docs. So we all get to help each other by gradually improving the docs. And if I help someone with something not in the docs then the recipient gets to include that missing info into the docs to help the next person.

We also added a hat for a rotating role called “Benevolent Documentation Czar for the Quarter” where that person gets to explicitly improve team docs. Maybe like 5% of their time.

Most of the problem is people don't know to look for it and so don't try. By asking them to help improve it that means I'm not shaming them for not looking at it and so they are more likely to read it. Also once in a while I get useful suggestions for improvement and so my documentation is now the best on the project, perhaps company (this is a very low bar)

So how exactly are you supposed to distinguish needing to improve the documentation from the fact that half the population—through no fault of their own—might be fundemenetally incapable of understanding the documentation? You can only polish something so much. Without a limiting principle this becomes unfalsifiable and an endless time sink.

As a general rule you cannot get a job working in my area without fluency in English. Probably the majority of the people who work with my code have English as a second language (I work with people in Germany, India, Mexico, and Brazil that I know of), but English is a requirement to work with my area. There are probably people in sales and support areas who don't speak English, but if they need to work with me they need a translator. (I'm lucky to be a native English speaker, but there is no reason I couldn't learn a different language)

if the person is incapable of, or unwilling to, read documentation which you think they should, you can ask them honestly about it, or ask your manager about it

if management feels this person is unqualified to be in their job, they can take care of the issue

"rtfm" or the AI equivalent is being snarky while dodging the issue that you should just talk about, which is that you think this person is asking you too many questions