Rails 3 Has Great Documentation | Hacker News Reader

Rails 3 Has Great Documentation

weblog.rubyonrails.org

76 pointsmhartl36 comments

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.

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.

For better or worse, I'm convinced that this is the reason that PHP took off the way it did. The documentation was clear, concise, easy to access (perhaps the first example of user friendly URLs I can remember), and effective; That each function had user-submitted (moderated) comments was the icing on the cake.

Being able to look at a function, have clear documentation WITH EXAMPLES was brilliant -- being able to see some of the common questions and resolutions from users was exemplary.

I know that the python docs are largely considered aces, but I have yet to see a language reference as good as the PHP documents. I hate the language, but it was the first language I could actually learn from its own documentation.

> I have yet to see a language reference as good as the PHP documents.

Here you go:

http://www.lispworks.com/documentation/HyperSpec/Front/index...

I've seen this (similarly highly-voted) comment made elsewhere. I just don't get it.

The PHP docs are often woefully incomplete in their explanation of functions. The user-submitted comments are the blind leading the lame, often containing competing solutions to the same problems, all of which are incomplete and poorly documented.

Aside from several highly-voted comments in discussions, though, the PHP documentation doesn't seem to be a frequently cited example of quality. I find that strange.

I seemed to be the only Python programmer who doesn't like its documentation page.

Programming tool that have the best documentation, to me, is jQuery. I think it's even better than php.net

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.

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

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

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.

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

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.

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

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.

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

Compare that with this: 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.

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

[2] http://cupi2.uniandes.edu.co/site/images/recursos/javadoc/j2...

"Compare that with this: 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]

As a very occasional Python user, it was very informative for me to see that String is a Sequence type. That immediately tells me something very important about Python, that I might be able to use similar functions and methods on lists, tuples, etc.

It's this comprehensiveness of the documentation that has impressed me before when I've needed to look things up about Python, and was enlightened about things I didn't expect to be.

I agree that all of that needs to be made clear in the documentation, but that need doesn't directly entail everything being on one page. What if the string page noted at the top that was inherited from the sequence type, or displayed sequence's methods as well as string's methods, and noted that they there are from sequence?

That would work just as well, I think.

There's a bit of serendipity in a big page like that, where you can learn more than you expected. But it comes at the cost of distracting you from whatever it was you came to find.

If I remember that correctly, the 'one page' style of python documentation came only in rather recently (last couple of years, >2.3), and the previous style was split one many pages: http://docs.python.org/release/2.3.5/lib/module-string.html

Back then I always hoped for the single page, because I was beginning with the language and jumping up and down the toc table of the docu page to figure stuff out. For a beginner, having this possibility to switch from birds to frog perspective inside one page is really great. They could do a better job on integrating the page-internal toc navigation though.

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!)

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.

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.

Reply on news.ycombinator.com