3 ms·

Interesting discussion. Thanks for posting. As I've gotten to learn many different languages (PHP, Ruby, Go, Java, Python, etc) over the last 10 years, it has

Interesting discussion. Thanks for posting. As I've gotten to learn many different languages (PHP, Ruby, Go, Java, Python, etc) over the last 10 years, it has been really interesting to see how different languages and communities can vary so wildly in their quality of documentation. As it relates to programming languages, Go's "Tour of Go" (https://tour.golang.org/welcome/1 https://tour.golang.org/welcome/1) is an excellent introduction to the language. I wish every language had an intro guide as good. In terms of frameworks, I absolutely love the Ruby on Rails guides. They strike the right balance between staying high level enough for me to build a mental model of how the framework is working under the hood, while getting deep enough to be useful to solve individual problems I have. Overall, I think the Ruby community has done a great job of documenting their libraries and frameworks. Whether it's Rails or Sinatra, or it's a library like Devise, Ruby OSS projects seem to tend towards thorough documentation. On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation.

agentgt 10y ago
> On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation. I actually find the opposite with Java libraries. They are generally over documented but are complete. The issue is that many have issues with publishing doc/Javadoc (with github it is slightly non trivial) and thus are outdated. Java projects have also been around a lot longer so some of them use archaic doc formats like docbook (spring). However the biggest problem with Java documentation is the accessibility of the standard language + javax stuff (ie jdk + jee). IMO Oracle does a piss poor job of this. You have to register and it is either in some messed up help tree format or some PDF that is impossible to download. On the other hand Apache and Spring I think are far far far more detailed in documentation than your standard PHP, Ruby, Python projects. The documentation may not be as pretty but it is there. I stress that because many languages and libraries lack specifications or review processes (even still) and Java was doing it fairly early (albeit with various corporate agendas).
heartsucker 10y ago
Since this is all about docs, having gone from Java/Scala to Rust, I cannot emphasize enough how much better Rust is at this. With `cargo doc` I get a local set of static files for the exact version of the libraries I'm using. Why can't everything be this easy?
- agentgt 10y ago
  It is that easy with Java/Scala... if... you are using an IDE. Eclipse through the maven plugin (m2e) will auto download the source code and will show doc as you code (along with drilling into the code. Intellij does something comparable as well. Racer can do this as well (and I admit far nicer in that it is editor agnostic). The problem is the tools for Java/Scala are all over the place so developers have different experience with the language that probably have very little to do with the language itself (syntax and libraries) but rather the tools. I would agree Rust is not the norm and IMO perhaps even the gold standard of what modern language organization and tooling should be. Java/Scala should probably have better builtin tools (or atleast mutually agreed on tools like auto formatting, editor agnostic completion /refactoring (ala racer), package management (Java is actually decent on this as maven is the standard), etc).
EtienneK 10y ago
> On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation. I'm not sure if you are serious? Spring's documentation is some of the best I've ever seen.

agentgt 10y ago

> On the flip side, Spring's documentation (and most Java library documentation) is absolutely atrocious. Spring in particular only seems to give you 2 flavors of documentation: a 10-minute tutorial, or a 1000-page deep dive in all of the corners of the framework. And Java libraries in general seem to have miserable, out-of-date, incomplete documentation. I actually find the opposite with Java libraries. They are generally over documented but are complete. The issue is that many have issues with publishing doc/Javadoc (with github it is slightly non trivial) and thus are outdated. Java projects have also been around a lot longer so some of them use archaic doc formats like docbook (spring). However the biggest problem with Java documentation is the accessibility of the standard language + javax stuff (ie jdk + jee). IMO Oracle does a piss poor job of this. You have to register and it is either in some messed up help tree format or some PDF that is impossible to download. On the other hand Apache and Spring I think are far far far more detailed in documentation than your standard PHP, Ruby, Python projects. The documentation may not be as pretty but it is there. I stress that because many languages and libraries lack specifications or review processes (even still) and Java was doing it fairly early (albeit with various corporate agendas).

heartsucker 10y ago

Since this is all about docs, having gone from Java/Scala to Rust, I cannot emphasize enough how much better Rust is at this. With `cargo doc` I get a local set of static files for the exact version of the libraries I'm using. Why can't everything be this easy?

agentgt 10y ago
It is that easy with Java/Scala... if... you are using an IDE. Eclipse through the maven plugin (m2e) will auto download the source code and will show doc as you code (along with drilling into the code. Intellij does something comparable as well. Racer can do this as well (and I admit far nicer in that it is editor agnostic). The problem is the tools for Java/Scala are all over the place so developers have different experience with the language that probably have very little to do with the language itself (syntax and libraries) but rather the tools. I would agree Rust is not the norm and IMO perhaps even the gold standard of what modern language organization and tooling should be. Java/Scala should probably have better builtin tools (or atleast mutually agreed on tools like auto formatting, editor agnostic completion /refactoring (ala racer), package management (Java is actually decent on this as maven is the standard), etc).

EtienneK 10y ago