I think the JavaScript ecosystem did a great job at this. Take a look at the documentation of React/Vue/Svelte; it is fascinating how they make it so accessible, both for newcomers and experienced developers in the field.

In contrast, the Java ecosystem has been really bad at documentation in my experience. Most of it is just explanations of function signatures, without any words on how those functions work as a whole system. The situation is even worse on Android, where there are dozens of standard APIs to achieve the same functionality.

▲ skydhash 5 days ago | parent [-]

Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)

▲ maxloh 4 days ago | parent | next [-]

As far as I recall, many libraries in the Java ecosystem, as well as the Android API, don't have the official tutorials or guides you're referring to. The JavaDoc and the Android API reference are often the only officially available resources.

So no, Those aren't just there to refresh developer's memory. In many cases, they are the only resource for learning the system from scratch.

▲ throwaway2037 5 days ago | parent | prev | next [-]

About JDK Java docs:

    > Those are references, not tutorial.

This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).

	▲	maxloh 4 days ago \| parent [-]
		I also occasionally fall back to the source when the documentation isn't comprehensive enough. But as library users, we're generally not supposed to have to learn the system from its source, aren't we?

▲ mschuster91 5 days ago | parent | prev [-]

> Usually you look for code examples or a guide for learning how those work

... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more.

The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.

	▲	skydhash 4 days ago \| parent [-]
		I was reading The Art of Unix Programming (E. Raymond) and one of the advices was that every library should come with a program. So even it’s a todo list kind, I think it’s quite nice to have.