I do a lot of GCP work anymore, and the amount of devs who make service authentication way more complicated than it needs to be is really freaking high. It's clear that the people who kicked off the project are pulling blocks from SO rather than RTFM because the FM has a simple decision tree for how to use authentication. Reading through the docs could have saved these projects each hours of time, simplified deployment and reduced the security risks associated with passing around json auth tokens (or worse: checking them into VCS.
- Beginners do not understand doc's jargon, or they need to learn too much stuffs to understand it that they'd rather quit. So they end up relying on third party sources/implementations
- No English knowledge and no translations
I have a spanish-speaking group where me and others teach beginners programming, and many of them cannot use the docs, whether because of a language barrier, or a lack of foundational knowledge, and all they care is to get things done, otherwise they'd get discouraged and abandon it before even starting
People generally just want to cut corners and 'be done with it' which simply results in lower quality.
Everyone of your users will start off as a beginner, it behooves project creators to ensure that beginner documentation is great.
“But the docs are poorly written” you say
“But the docs aren’t maintained well” you say
Read the docs. Sometimes it isn’t supposed to be easy. Or fun. Or fit together well. But that’s the job.
RTFM is the best technical advice I’ve been given and can give.
In practice, difference between it and Oracle docs was negligible. Hell. Their auto-gen code was more self explanatory than Oracle Java Docs.
new Doer(UnrelatedFactory.create("foo", new WTFBar(), 5, null, null), RandomEnumFromADifferentPackage.MEANINGLESS_VALUE, true).do()
But I'm not really convinced such documents are helpful. I mean, technically they're better than nothing (as in, literally better than nothing), but the difference between nothing and those docs is so small it approaches nothing ('as the worthlessness of the documentation approaches infinity the value of reading them approaches nothing', as it were)
For instance, searching for "Java read a file", I find a bunch of examples. And they mostly are good enough, call out when they aren't, and provide useful links.
Meanwhile, navigating Oracle's website is a nightmare. https://docs.oracle.com/javase/tutorial/essential/io/file.ht... exists, and is actually pretty helpful, but the only way I was able to find it was by Googling "oracle java read a file". Searching Oracle's own doc site (itself hard to find for a given version of Java) with the same string (i.e., 'read a file') turned up nothing useful ( https://docs.oracle.com/search/?q=read+a+file&category=java&... )