

Rails 3 Has Great Documentation - mhartl
http://weblog.rubyonrails.org/2010/8/28/rails-has-great-documentation

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

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

~~~
WalterGR
_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._

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.

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

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

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

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

~~~
jshen
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
The django docs are rather good and similar in many ways to python docs:
<http://docs.djangoproject.com/en/1.2/>

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

~~~
michaelfairley
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>

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

~~~
jamesbritt
"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]

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

