[irahul]

> It's hard to find any language that has better online documentation than Java.

I don't see how http://docs.oracle.com/javase/6/docs/api/ this is better documentation than http://docs.python.org/library/random.html or http://perldoc.perl.org/perlretut.html

Java docs are mostly a dump of class hierarchies with some comments documenting the functions. Python and Perl docs are written as user guides compared to Java api dumps.

[RodgerTheGreat]

In addition to the API documentation, there's the "Java Learning Trail", which is a set of step-by-step tutorials with numerous screenshots and tons of example code:

http://docs.oracle.com/javase/tutorial/java/index.html

Additionally, if you actually page through the Java API documentation, many packages contain overviews describing rationale and how everything fits together- hardly a "dump of class hierarchies with some comments". For example,

http://docs.oracle.com/javase/1.4.2/docs/api/java/awt/doc-fi...

Personally I think having both a tutorial and browsable API documentation is preferable to dealing with unstructured prose for everything.

[irahul]

> In addition to the API documentation, there's the "Java Learning Trail", which is a set of step-by-step tutorials with numerous screenshots and tons of example code:

If you are already a programmer, you will be able to complete this tutorial in less than 2 hours http://docs.python.org/tutorial/, and can start programming Python. Want to learn Perl? http://www.perltutorial.org/. This tutorial thing isn't something that is unique to java, and personally, I find the Perl and Python versions higher quality compared to Java's tutorial.

> Personally I think having both a tutorial and browsable API documentation is preferable to dealing with unstructured prose for everything.

Unstructured prose for everything? What are we talking about? How is http://docs.python.org/library/random.html (description, methods and usage, example code) unstructured prose? When it comes down to which doc is better, it comes down to personal preference. But Java has the best online documentation is far from the truth.

[jbooth]

I'd compare your python link to http://docs.oracle.com/javase/6/docs/api/java/util/Random.ht... rather than the doc root.

[irahul]

Fair enough. May be it's me but I find Python/Perl docs more intuitive. I find it difficult to figure out how to do something by reading Java docs.

Personal preferences aside, I would say Python/Perl docs are as good as, if not better, than the Java docs. Ruby's documentation is not as good, but rails documentation is very good http://guides.rubyonrails.org/ For C, we have the man pages(though archaic, they are pretty good). My point is I don't see how Java leads in terms of online documentation.

[jbooth]

I was more saying that there's no lack of documentation than saying Java wins in a documentation-off with any other language. Seems to me the differences are mostly in style, they all include descriptions of each method on a given type and a description of intended usage. Java will typically only have sample code if the usage pattern is more complex than that of Random.