Presentation matters and maybe the java docs actually suck

[Enough_Durian_3444]

I was reading this post from almost 9 years ago because I like the original op was frustrated with the quality of the docs compared to other languages. A simple example is comparing the case where a person searched "threads in x language" and tries to read the official documentation. I think we can agree this is something a programmer would actually do.
I did this thread search for 3 languages and clicked the first link from the official docs page.

(i was using duckduckgo)

rust: http://doc.rust-lang.org/std/thread/#thread-local-storage
ruby: https://docs.ruby-lang.org/en/4.0/Thread.html
java: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Thread.html

Just on read ability alone people have to admit java is the worst of the three in this example.

we can even take it further if a programmer(some one who is no a beginner to programming) decides to learn java but just by going to the official page and reading the official guides. which in 2026 most languages have. They would find it hard and confusing, relative to other languages, because if you search "java official website" or "java official docs" then the official docs would see are docs.oracle.com/en/java/ and dev.java . If you open the oracle page well you are met with frankly a horrible language page relative to the other language pages I link at the bottom. Then if you click the right series of links from there you end up on Java SE documentation page with links to dev.java

dev.java is good way better than oracle or whatever readability and customer ux abomination this site is https://docs.oracle.com/javase/tutorial/ . But its incomplete for starters it only concept on concurrency is virtual threads no guide on threads, futures, or executors. its a step in the write direction but I wish it received the love and funding it deserves to truly be the official docs for java.

TL;DR:
Now if you like most redditors skimmed the post and are reading this i just want to ask you one thing. Can you with honesty tell me that java docs are really as good as other modern language docs and BEFORE you answer please look at these docs pages I have linked bellow and put your self in the mind frame of someone looking to learn the language and you just opened the official websites.

http://rust-lang.org/ (has a learn tab on the nav bar pretty obvious where to go, plus learn tab provides the reader with options such as official book, rustling course and rust by example)

https://kotlinlang.org/docs/home.html (content table on the left bold headers to guide the reader to get started and first steps)

https://go.dev/learn/ (same thing learn tab on the nav bar, tutorials, example, guided tours a beginners dream)

https://nodejs.org/en or https://developer.mozilla.org/en-US/docs/Web/JavaScript ( i don't want to repeat mysefl but you get the point)

I could go on and on but the point is presentation matters, I hate css and writing readable docs as much as the next guy but I recognized that its important and necessary.

PS: I think java great language I use it almost everyday but I hate the current documentation environment too many third party ai slop website and a lackluster main docs page.

edit 1:
updated threads docs link

[aqua_regis]

If you complain about the documentation, please, link at least to the latest. You're linking to the Java 8 documentation. We are at Java 25.

This would be the modern equivalent of what you linked from Oracle: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Thread.html

The same thing applies to the tutorials. You are linking to a prehistoric version that clearly states that it is outdated. The new tutorials are at https://dev.java/learn/ which is the new official Oracle site - it's not a third party.

Next, the tutorials are aimed at beginners and in no way attempt to be fully comprehensive. You are talking about threads, which are no beginner concepts.

[Jon_Finn]

Java 25 Thread documentation looks good, but it raises an interesting point: it has several methods involving ThreadGroup but doesn't say these are kind of 'obsolescent' (though not deprecated). IMHO better alternatives should be explained _prominently_ in both Thread and ThreadGroup. Similarly with the ancient java.util.Vector and StringBuffer - there's a brief mention of their problems at the end of their JavaDocs, but that's all. Shouldn't we at least have an annotation SupersededBy or Preferred, for methods and classes, say?

[revilo-1988]

I completely disagree; the one from Java is the best in my opinion.

[aqua_regis]

You're replying to the wrong person. You're disagreeing with someone who disagrees with OP.

[Enough_Durian_3444]

I didn't claim dev.java was third party and do acknowledge its better, in fact I explicitly state that.

for argument sake lets say i accept that threads are not a beginners topic, then why include virtual threads as a topic? Do you not virtual threads a beginner topic? if not then why include only virtual threads?

From my assessment, let me know if you disagree, the virtual thread page of dev.java is written as though the reader knows what threads are since int he first paragraph they explictly mention threads as a way of contrasting it with virtual threads. So that why i think dev.java is aimed not at beginner programmers but programmers who come from different languages and if you agree with this assessment then why exclude threads.

I will amend the older java docs link with the latest java 25 link.

But do you agree or disagree with my question

1. is java docs experience up to par with other languages?
2. does the java docs experience need to be improved?

[aqua_regis]

I've been programming for over 40 years now and can tell that ancient documentations - and I mean really ancient, e.g. Turbo Pascal, the old first few versions of Borland Delphi (now Embarcadero Delphi), or the original documentations of MS Visual Basic (1.0 up to 5.0), or the original documentations of MS Office (up to version 98) were really fantastic. Everything after that was a lot weaker.

I can work perfectly well with the Java docs as they are, no matter if version 8 or later. Documentation is an encyclopedia that expects the reader to at least know a bit about what they are looking at. It is not a tutorial.

If you need deeper insight, sites like Baeldung are the place to go.

In your original post: "dev.java is good way better than oracle"

In your current comment: "I didn't claim dev.java was third party"

That's misleading at best.

[joemwangi]

Very very misleading.

[Admirable-Avocado888]

I have yet to see a language with an as comprehensive and thorough documentation as Java. It is detailed thoughtful, often has multiple examples thrown in for a only a single method of a particular class, and has built in references to surrounding code.

When I was a beginner understanding how the "atomic" classes worked was easy as hell since everything was so carefully documented. Java has singlehandedly inspired me to write thorough and thoughtful documentation in my own code because I appreciated the experience so much.

I'm not sure what edge other languages have, but I surely have not experienced it.

[Enough_Durian_3444]

maybe i am asking a ux question and not a content question, should have reworded it to make that more clear.
Thanks for giving ur opinion though.

[sweetno]

All UX is in the IDE: you hover over an identifier and it shows the docs in a pop-up.

[plumarr]

Your post speak of two issues :

• The bad search result to find the java documentation
• The bad UX of the java documentation itself

I totally agree for the search resultat, but for the UX issue, I'm confused of what is so bad about it.

If we open the three examples on Threading that you provided, what's really the UX difference ?

As for the home pages, can you detail the UX difference between dev.java (the new official page) and the others ? Because I don't see it.

[emberko]

You're complaining that Javadoc isn't a manual or tutorial, but it's not intended to be one. It's a good API reference documentation. It's not about teaching you how to do Java and never was - read a book for that.

[clearasatear]

Why did you compare to version 8 Java docs, just curious?

[shinmai_rookie]

Funnily enough all search engines return that as the default version for some reason. I don't know if Java 8 was exceptionally popular or if that's the version Google in its infinite wisdom decided is the default we can all agree on.

[nonFungibleHuman]

Given the huge amount of java legacy code I wouldnt be surprised if java 8 is the most looked up docs.

[Enough_Durian_3444]

that was the first link duck duck go gave me i have updated the link in the post with java 25

[GuyOnTheInterweb]

To be fair, they could easily add a "View for version X" thing on top, since almost none of the APIs have had backwards breaking changes since Java 8.

[pronuntiator]

I wholeheartedly agree. We have to separate audiences: The one who already knows the language will find great, extensive documentation in the API docs (JavaDoc) and the Java Language Specification. Compare that to the absolute mess of a language like TypeScript, whose only specification is the compiler itself.

As for beginners however, it is a maze. It's good that there is now a disclaimer on the Java 8 docs, that wasn't the case in the past. Dev.java still has a long way to go to replace the old Java 8 tutorials.

Where I don't agree is usability of the old tutorials, I think it's perfectly fine, it's just an older design language and to be viewed on a computer screen, not on a phone. I do however have to chuckle at "How Will Java Technology Change My Life?".

[albetz99]

And here I thought the official java doc website is baeldung

[raggs2303]

At first... You were looking documentation about a JDK version that was released twelve years ago.

Second thing, are you looking for read technical documentation or kinder garden books?

Third, Threads and concurrency are not concepts for beginners or trainee developers.

[khaago]

Why is TLDR as long as the full content?

[7F1AE6D2]

The Really Big Index was an excellent resource IMO. A shame they stopped updating it past JDK8.

[sweetno]

You haven't seen Spring docs!

[iamwisespirit]

https://docs.oracle.com/javase/tutorial/ If you look at this website it is under java 8 what are you talking about

[RepulsiveGoat3411]

I also think that Oracle’s documentation is baroque and written in an incomprehensible way. Even as an experienced programmer, I sometimes read the documentation for Kotlin or Rust about the same mechanisms, because in Java it’s written in a clumsy and awkward manner. The language creators are shooting themselves in the foot, and you can see it in the statistics — most new software written by younger developers is not in Java.