4 ms·

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

by pmorici 16y ago

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/ 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 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.

nikz 16y ago
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 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/ http://phrogz.net/programmingruby/). Admittedly old versions, but well organised by-topic nonetheless.
jshen 16y ago
I actually prefer this format http://api.rubyonrails.org/ 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.
- wwortiz 16y ago
  Ctrl-f only works if you know what you are looking for though.
  - nex3 16y ago
    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.
    - wwortiz 16y ago
      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.
      - dasil003 16y ago
        Far and wide? Just start with Rails Guides (http://guides.rubyonrails.org/ http://guides.rubyonrails.org/). When you are somewhat familiar you can find details in the API docs (http://api.rubyonrails.org/ http://api.rubyonrails.org/).
      - jshen 16y ago
        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.
        wwortiz 16y ago
        The django docs are rather good and similar in many ways to python docs: http://docs.djangoproject.com/en/1.2/ http://docs.djangoproject.com/en/1.2/
      - deleted 16y ago
catch23 16y ago
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".
- pmorici 16y ago
  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/ 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/ 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.
  - slillibri 16y ago
    The ruby stdlib seems to follow a different documentation format then everything else ruby. Look to http://www.ruby-doc.org/core http://www.ruby-doc.org/core for what is the standard documentation format (not that I like it much better).
    - catch23 16y ago
      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".
jimbokun 16y ago
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."

by pmorici 16y ago

nikz 16y ago

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 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/ http://phrogz.net/programmingruby/). Admittedly old versions, but well organised by-topic nonetheless.

jshen 16y ago

I actually prefer this format http://api.rubyonrails.org/ 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.

wwortiz 16y ago
Ctrl-f only works if you know what you are looking for though.
- nex3 16y ago
  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.
  - wwortiz 16y ago
    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.
    - dasil003 16y ago
      Far and wide? Just start with Rails Guides (http://guides.rubyonrails.org/ http://guides.rubyonrails.org/). When you are somewhat familiar you can find details in the API docs (http://api.rubyonrails.org/ http://api.rubyonrails.org/).
    - jshen 16y ago
      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.
      - wwortiz 16y ago
        The django docs are rather good and similar in many ways to python docs: http://docs.djangoproject.com/en/1.2/ http://docs.djangoproject.com/en/1.2/
    - deleted 16y ago

catch23 16y ago

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".

pmorici 16y ago
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/ 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/ 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.
- slillibri 16y ago
  The ruby stdlib seems to follow a different documentation format then everything else ruby. Look to http://www.ruby-doc.org/core http://www.ruby-doc.org/core for what is the standard documentation format (not that I like it much better).
  - catch23 16y ago
    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".

jimbokun 16y ago

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."