Hacker News Reader

Comment by pmorici | Hacker News Reader

The author more or less proves the exact opposite. The API docs are what matters most and Ruby's suck. Looking at this, http://railsapi.com/doc/rails-v3.0.0RC/ for a moment which the author cites as a good resource. If I were a beginner with the language how would I know what the heck any of this stuff is. The index is organized by class name instead of purpose. Compare that to Python's documentation, http://docs.python.org/library/index.html which is organized by purpose, ie: all the string stuff is under a section titled "String Services". Python is a gold standard for documentation is this regard as I've seen few if any other languages arrange their docs in such a intuitive way.

The mere existence of documentation doesn't make it great.

View on HN

I was looking up some Python documentation not long ago, and was shocked by how well it was written. Definitely agree that it is the gold standard. Documentation quality should probably feature more highly in the never ending discussions about "what's the best language."

The API documentation is probably not where you want to look in this instance. It's more intended for looking up the behaviour or options for a specific method call.

http://guides.rubyonrails.org is the equivalent of the Python documentation you point to for Rails.

If you want Ruby-specific documentation, there are versions of the Pickaxe book online (http://phrogz.net/programmingruby/). Admittedly old versions, but well organised by-topic nonetheless.

I actually prefer this format http://api.rubyonrails.org/. Everything is there, and I can use cmd-f to search for whatever. It's probably because I'm familiar with it, but that's probably why you like python's.

Ctrl-f only works if you know what you are looking for though.

That's the difference between reference documentation and introductory documentation. You go to reference documentation when you want to look up the details of something you already know; you go to introductory documentation if you want to learn it for the first time.

Okay sure, but how do you get from the introductory docs (which are far and wide, as well as lacking in quite a few areas) to reference documentation. I can see how ruby-doc can be a good resource but only for those that know the language and know what they should be looking for, even then though sometimes docs like python's are better references.

Far and wide?

Just start with Rails Guides (http://guides.rubyonrails.org/). When you are somewhat familiar you can find details in the API docs (http://api.rubyonrails.org/).

there are also two great books, the agile rails book, and the rails way. They will get you started, and may be 90% of what you need. The docs are good for the rest.

One thing though, we're comparing apples and oranges; the docs for a web framework vs the docs for a standard library. Are the django docs similar to the standard lib docs?

I'm not trying to dis python, I really like python and use it whenever I need to do mathy stuff with numpy and scipy. Most other things I do in ruby.

The django docs are rather good and similar in many ways to python docs: http://docs.djangoproject.com/en/1.2/

Why are you comparing a framework's documentation to a language docs? I would assume people using rails would already know ruby so it wouldn't make sense to categorize their documentation using some kind of arbitrary categorization. If you prefer docs on how "X" should be done, you should get a language/framework "cookbook".

Most Python modules follow Pythons lead on the documentation front, look at Django for example if you want to compare apples and apples, http://docs.djangoproject.com/en/1.2/

The documentation for Ruby itself doesn't appear to be much different then Rails, http://www.ruby-doc.org/stdlib/ difficult to read and follow.

I've never needed a "cookbook" for Python, because the ingredients are clearly labeled and arranged and I'm already an experienced chef.

The ruby stdlib seems to follow a different documentation format then everything else ruby. Look to http://www.ruby-doc.org/core for what is the standard documentation format (not that I like it much better).

That format comes from smalltalk. Ruby inherits lots of their ideology from smalltalk so it's no surprise to see them adopt their class browser either. However, I'm not sure if class browsers can be considered "documentation".

Reply on news.ycombinator.com