6 ms·

Rails 3 Has Great Documentation

76 points by mhartl 16y ago

wwortiz 16y ago
Isn't that only from a large community, when I think of documentation I think of a central place to find it and this is why I use python and not ruby. As an aside the ruby docs are annoying for me to use however I quite enjoy the way pythons docs are built. Similarly when you look at this post you see that rails has "great" documentation through the means of a large amount of differing non-central sites that require some effort to go about finding as well as navigating. Though it is much better than when rails was still young.
- petercooper 16y ago
  Yeah. In my experience, Rubyists are more likely to be solo developers, self starters and/or be keen to improve things/reinvent wheels rather than necessarily work on "official" projects with all the bureaucracy that's involved. I wouldn't dare to speak for all Rubyists but, in general, I'd say the typical Rubyist is very anti-bureaucracy (more so than developers of any other group I've experienced). There have been tons of Ruby documentation sites over the years and if all that effort had been put into developing a good system for the "official" documentation, it'd probably the best of any language ;-) But Ruby is very "long tail" when it comes to deciding what sites to read, mailing lists to use, etc. There are few de facto points of congregation. That said, I'm not criticizing, because I'm the same (I want to run my own gigs, not fit in with someone else's system) and that's what I like about Ruby and Rubyists. You don't get a single "official" book of documentation about math, architecture, or English language syntax. Instead, everyone releases their own attempts and a wide variety of viewpoints and coverage is available. In this way, Ruby feels more like a discipline or "way" of doing things than a single, specified entity that can be centrally documented well. (I'm talking from a Ruby POV rather than a Rails one, since you brought up Ruby specifically in comparison to Python. Rails has a much more bureaucratic and centralized community than Ruby does. Rails' official documentation is also miles ahead of Ruby's.)
  - wwortiz 16y ago
    There really is a ruby way of doing things and from the outside it is interesting but not something I feel like I would benefit from. Ruby moves fast and the community moves fast with it and this doesn't fit me well or the way I work.
- steveklabnik 16y ago
  > when I think of documentation I think of a central place to find it While your other points still stand, there is quite a bit of central documentation, and it's mentioned in the article. The fact that there's also a ton of extra documentation that other people have done in other places is just icing on the cake.
  - wwortiz 16y ago
    Even the central documentation is split between two subdomains with edge cases for each. You have the api reference and then you have the guides (which is much better docs but still lacking in navigation and extensiveness.) It isn't necessarily a bad thing the way rails docs are, personally I just think the ruby community moves way too fast and in that the extensive docs tend to suffer.
- michaelfairley 16y ago
  Python docs aggravate me in numerous ways. One main complaint is that there is a single page[1] for all of the standards types (boolean, string, list, dictionary, numbers, etc.) that contains way too much disjointed information. It could really stand to be split into a few different pages, as it's annoying that Googling "python string", "python list", python int", etc. all lead to top of the same exact page. [1] http://docs.python.org/library/stdtypes.html http://docs.python.org/library/stdtypes.html
  - wwortiz 16y ago
    Compare that with this: http://ruby-doc.org/ruby-1.9/index.html http://ruby-doc.org/ruby-1.9/index.html I find that page (docs.python.org) easy to navigate using the side menu and the structure of the document the fact that it is so big doesn't quite bother me, I already know most of what I need on that page and wouldn't be upset navigating it if I had to.
    - michaelfairley 16y ago
      I in no way said that the python docs were worse than the ruby ones, only that the python docs are really not as great as they could be. You already knowing everything on the page doesn't make it any less poorly designed. I find it much more preferable to be able to search for "python string" on Google and be brought straight to a page about strings, not about every type in the languages (Ruby[1] and Java[2] both do this sanely.) The formatting within the python docs is also highly inconsistent. Why (on the built-in types page) do the operations on sequence types (5.6) get a nice table, but the operations on sets (5.7) have a poorly formatted list? [1] http://ruby-doc.org/core/classes/String.html http://ruby-doc.org/core/classes/String.html [2] http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2se/1.5.0/docs/api/java/lang/String.html http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2...
    - jamesbritt 16y ago
      "Compare that with this: http://ruby-doc.org/ruby-1.9/index.html http://ruby-doc.org/ruby-1.9/index.html I have on my recklessly large to-do list plans to update the API docs on ruby-doc.org with YARD. The template seems a bit easier to navigate and the overall results better. But I'm always open to concrete suggestions. [note: I run ruby-doc.org]
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.
viraptor 16y ago
I'm not a rails person, but I had a look at the api docs he decided to link as an example... And I understood why people might be complaining. I started with railsapi.com - selected something at random: first ActionView::Layouts (seems like a crucial class): find_layout(layout) - This is the method which actually finds the layout using details in the lookup context object. If no layout is found, it checks if at least a layout with the given name exists across all details before raising the error." Right... where does the "lookup context" object go? What is "layout" What's returned? Where does it "find the layout"? Why does this method exist? What error is raised? Ok - maybe I just chose something that's not popular - another try is ActionView::PathResolver: to_path() - Alias for to_s to_s() - This method is also aliased as to_path You're kidding me, right? Ok - something easy this time - "Float" -> "round(precision = nil) - Rounds the float with the specified precision." Rounds which way? What type of rounding is used? How does it behave for infinities and -epsilon? Something important "I18n" - there is NO documentation at all. I checked APIdock, thinking it might be better - it took a lot of clicking to get to a class which had any documentation at all (ActiveRecord in this case). If you check "browse", you'll see yourself how many classes lack any kind of description... Summing up - I'm not sure about the screencasts, guides, etc., but API docs are almost non-existent.
- dasil003 16y ago
  Rails is not a library. It wouldn't serve anybody to write a dissertation in every file about how that file fits into the whole framework. Rails API documentation is far from perfect, but a surprising amount of the important stuff is covered in a few consolidated locations. The documentation for some modules is often consolidated in a more central location so you can get a better overview of the whole API. See ActionController::Base, ActiveRecord::Base, ActiveRecord::Associations::ClassMethods for example. As for I18n, well, I18n is an external gem, it is not core to Rails which is why it is not documented there. No one is arguing that Rails API documentation is newbie friendly, but I would argue that the purpose of API documentation is not to introduce people to the framework; it's reference material. The Rails Guides are pretty good (if not lagging a bit for some aspects of Rails 3) and I would put them up against any other framework documentation I've used.
- 16y ago
sr3d 16y ago
This is awesome! I love the ability to drill-down to a specific method by fuzzy-searching! I was using gotapi.com for looking up help and reference, but they didn't scroll to the right method. Most people who complain about the Rails documentations site probably don't use Rails everyday since it's hard to appreciate something if you don't use it. I'm working with Rails almost everyday, and so far I enjoy it very much. The documentations are great, the Rails Guide is great (and very, very thorough and approachable), and the community is really active. As DHH said, all the arguments don't matter much once you start using Rails, since everything will all make sense (I believe this was in Rails keynote in 2009, he was referring to the debates between implementing .first, .second to the Array class, and he pointed out that these decisions were made to help developers think better and more expressive in their code and thus become happier -- and he's totally right!)
bstar 16y ago
So why are most of you comparing rails docs to python and php? Rails is a web framework, not a language. Look at the ruby api for an apples to apples comparison.
ayb 16y ago
Railscasts didn't exist when I first started using Rails in the fall of 2005 - they are an invaluable resource and just one of many the author points out. For someone who has not used Ruby before, it will likely take years to go from 0 to Ruby/Rails "Zen Master". The Ruby language seems simple at first but there are many nuances and powerful methods (such as #inject and #map) that few will master right away. Also with regards to Rails, there are a lot of "moving parts". Randomly picking something out of the API and expecting to understand it, outside of its context etc., is not the right way to go about this. Having been learning and working with Rails for several years now, I can tell you that there is must more excellent content now than ever before. And there will soon be plenty of Rails 3 specific books available too.

76 points by mhartl 16y ago

Isn't that only from a large community, when I think of documentation I think of a central place to find it and this is why I use python and not ruby. As an aside the ruby docs are annoying for me to use however I quite enjoy the way pythons docs are built. Similarly when you look at this post you see that rails has "great" documentation through the means of a large amount of differing non-central sites that require some effort to go about finding as well as navigating. Though it is much better than when rails was still young.

petercooper 16y ago
Yeah. In my experience, Rubyists are more likely to be solo developers, self starters and/or be keen to improve things/reinvent wheels rather than necessarily work on "official" projects with all the bureaucracy that's involved. I wouldn't dare to speak for all Rubyists but, in general, I'd say the typical Rubyist is very anti-bureaucracy (more so than developers of any other group I've experienced). There have been tons of Ruby documentation sites over the years and if all that effort had been put into developing a good system for the "official" documentation, it'd probably the best of any language ;-) But Ruby is very "long tail" when it comes to deciding what sites to read, mailing lists to use, etc. There are few de facto points of congregation. That said, I'm not criticizing, because I'm the same (I want to run my own gigs, not fit in with someone else's system) and that's what I like about Ruby and Rubyists. You don't get a single "official" book of documentation about math, architecture, or English language syntax. Instead, everyone releases their own attempts and a wide variety of viewpoints and coverage is available. In this way, Ruby feels more like a discipline or "way" of doing things than a single, specified entity that can be centrally documented well. (I'm talking from a Ruby POV rather than a Rails one, since you brought up Ruby specifically in comparison to Python. Rails has a much more bureaucratic and centralized community than Ruby does. Rails' official documentation is also miles ahead of Ruby's.)
- wwortiz 16y ago
  There really is a ruby way of doing things and from the outside it is interesting but not something I feel like I would benefit from. Ruby moves fast and the community moves fast with it and this doesn't fit me well or the way I work.
steveklabnik 16y ago
> when I think of documentation I think of a central place to find it While your other points still stand, there is quite a bit of central documentation, and it's mentioned in the article. The fact that there's also a ton of extra documentation that other people have done in other places is just icing on the cake.
- wwortiz 16y ago
  Even the central documentation is split between two subdomains with edge cases for each. You have the api reference and then you have the guides (which is much better docs but still lacking in navigation and extensiveness.) It isn't necessarily a bad thing the way rails docs are, personally I just think the ruby community moves way too fast and in that the extensive docs tend to suffer.
michaelfairley 16y ago
Python docs aggravate me in numerous ways. One main complaint is that there is a single page[1] for all of the standards types (boolean, string, list, dictionary, numbers, etc.) that contains way too much disjointed information. It could really stand to be split into a few different pages, as it's annoying that Googling "python string", "python list", python int", etc. all lead to top of the same exact page. [1] http://docs.python.org/library/stdtypes.html http://docs.python.org/library/stdtypes.html
- wwortiz 16y ago
  Compare that with this: http://ruby-doc.org/ruby-1.9/index.html http://ruby-doc.org/ruby-1.9/index.html I find that page (docs.python.org) easy to navigate using the side menu and the structure of the document the fact that it is so big doesn't quite bother me, I already know most of what I need on that page and wouldn't be upset navigating it if I had to.
  - michaelfairley 16y ago
    I in no way said that the python docs were worse than the ruby ones, only that the python docs are really not as great as they could be. You already knowing everything on the page doesn't make it any less poorly designed. I find it much more preferable to be able to search for "python string" on Google and be brought straight to a page about strings, not about every type in the languages (Ruby[1] and Java[2] both do this sanely.) The formatting within the python docs is also highly inconsistent. Why (on the built-in types page) do the operations on sequence types (5.6) get a nice table, but the operations on sets (5.7) have a poorly formatted list? [1] http://ruby-doc.org/core/classes/String.html http://ruby-doc.org/core/classes/String.html [2] http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2se/1.5.0/docs/api/java/lang/String.html http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2...
  - jamesbritt 16y ago
    "Compare that with this: http://ruby-doc.org/ruby-1.9/index.html http://ruby-doc.org/ruby-1.9/index.html I have on my recklessly large to-do list plans to update the API docs on ruby-doc.org with YARD. The template seems a bit easier to navigate and the overall results better. But I'm always open to concrete suggestions. [note: I run ruby-doc.org]

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.

viraptor 16y ago

I'm not a rails person, but I had a look at the api docs he decided to link as an example... And I understood why people might be complaining. I started with railsapi.com - selected something at random: first ActionView::Layouts (seems like a crucial class): find_layout(layout) - This is the method which actually finds the layout using details in the lookup context object. If no layout is found, it checks if at least a layout with the given name exists across all details before raising the error." Right... where does the "lookup context" object go? What is "layout" What's returned? Where does it "find the layout"? Why does this method exist? What error is raised? Ok - maybe I just chose something that's not popular - another try is ActionView::PathResolver: to_path() - Alias for to_s to_s() - This method is also aliased as to_path You're kidding me, right? Ok - something easy this time - "Float" -> "round(precision = nil) - Rounds the float with the specified precision." Rounds which way? What type of rounding is used? How does it behave for infinities and -epsilon? Something important "I18n" - there is NO documentation at all. I checked APIdock, thinking it might be better - it took a lot of clicking to get to a class which had any documentation at all (ActiveRecord in this case). If you check "browse", you'll see yourself how many classes lack any kind of description... Summing up - I'm not sure about the screencasts, guides, etc., but API docs are almost non-existent.

dasil003 16y ago
Rails is not a library. It wouldn't serve anybody to write a dissertation in every file about how that file fits into the whole framework. Rails API documentation is far from perfect, but a surprising amount of the important stuff is covered in a few consolidated locations. The documentation for some modules is often consolidated in a more central location so you can get a better overview of the whole API. See ActionController::Base, ActiveRecord::Base, ActiveRecord::Associations::ClassMethods for example. As for I18n, well, I18n is an external gem, it is not core to Rails which is why it is not documented there. No one is arguing that Rails API documentation is newbie friendly, but I would argue that the purpose of API documentation is not to introduce people to the framework; it's reference material. The Rails Guides are pretty good (if not lagging a bit for some aspects of Rails 3) and I would put them up against any other framework documentation I've used.
16y ago

sr3d 16y ago

This is awesome! I love the ability to drill-down to a specific method by fuzzy-searching! I was using gotapi.com for looking up help and reference, but they didn't scroll to the right method. Most people who complain about the Rails documentations site probably don't use Rails everyday since it's hard to appreciate something if you don't use it. I'm working with Rails almost everyday, and so far I enjoy it very much. The documentations are great, the Rails Guide is great (and very, very thorough and approachable), and the community is really active. As DHH said, all the arguments don't matter much once you start using Rails, since everything will all make sense (I believe this was in Rails keynote in 2009, he was referring to the debates between implementing .first, .second to the Array class, and he pointed out that these decisions were made to help developers think better and more expressive in their code and thus become happier -- and he's totally right!)

bstar 16y ago

So why are most of you comparing rails docs to python and php? Rails is a web framework, not a language. Look at the ruby api for an apples to apples comparison.

ayb 16y ago

Railscasts didn't exist when I first started using Rails in the fall of 2005 - they are an invaluable resource and just one of many the author points out. For someone who has not used Ruby before, it will likely take years to go from 0 to Ruby/Rails "Zen Master". The Ruby language seems simple at first but there are many nuances and powerful methods (such as #inject and #map) that few will master right away. Also with regards to Rails, there are a lot of "moving parts". Randomly picking something out of the API and expecting to understand it, outside of its context etc., is not the right way to go about this. Having been learning and working with Rails for several years now, I can tell you that there is must more excellent content now than ever before. And there will soon be plenty of Rails 3 specific books available too.