Programmer Humor

From personal experience:

One part is manuals / docs being hard to use. Some seem to assume a measure familiarity with the subject, creating a certain entry barrier. They're perfectly usable as reference for people who know the gist but look up details, but for younger devs, it's disheartening to get the sense that you don't understand anything. That's a common issue with FOSS tools, in my experience, where the devs naturally prioritise developing the actual tool. Asking and getting an answer for a specific example can help get a foothold and start climbing that, but it's no guarantee.

A second part is that manuals don't always cover things you can't do (because obviously it's hard to predict what people would come up with wanting to do), but it's hard to tell whether that's just incomplete unless you ask and get an explicit, hard "nope". Bonus points for commercial products documenting what you can do, but not with your current license: You'll diligently read the page for what you want to do, attempt to implement it, then be hit with "please upgrade to Premium for this feature".

A third part is terminology. Just like the non-features, it's impossible to predict all the ways someone might describe what they want to do if they don't know any better way to phrase it. I'd count language barriers into this as well, which is an issue that a smaller, US-heavy software development world wouldn't have had to the same degree as we do today.

And finally, of course, there's convenience, which is where I think the managers have the greatest impact: The less time you have to spend learning how to RTFM or digging through the docs, the less time is "wasted" on things that aren't immediately productive. Particular non-IT-background managers may not appreciate the value of such skills, so they'd rather have you spend someone else's time taking a shortcut than invest your own.

So I think this is an issue arising naturally from several independent factors, which makes it hard to tackle effectively. Managers should plan for and encourage taking time to understand the manual, but I don't see a universal solution to the documentation quality and language barriers.

Also, retiring to have a farm is a mood.