Rails Has Great Documentation
Posted by Gregg Pollack August 28, 2010 @ 06:08 PM
To this day I still hear people complain that Rails has poor documentation. From where I’m sitting this seems far from the truth. Let me lay out the evidence piece by piece:
RailsTutorial.org
To learn Rails from scratch Michael Hartl recently finished his book Ruby on Rails Tutorial: Learn Rails by Example. The book teaches Rails 3 from the ground up and it’s available for FREE online. If you’d rather have a PDF or a book you can grab that as well (and he’s even working on some screencasts).
The source for the finalized book will be pushed to GitHub and released under a Creative Commons License shortly after Rails 3 is done. If you’d like to help translate the book to your language of choice, feel free to contact Michael and he’ll get in touch when it’s time to make it happen.
Rails Guides
If you’re not a Rails newbie don’t forget about the Rails Guides, which have been updated for Rails 3.
Rails API Docs
There are two main websites I use to do API lookups. The first is Rails Searchable API Doc, which has online and offline searchable documentation. The second is APIdock which is online only, but has the ability to comment and easily compare different versions of documentation.
Rails 3 Free Screencasts
If you’re more of a visual learner (like me) then there are plenty of free screencasts to teach you about Rails 3. About 2 months ago I produced the Rails 3 Screencasts, which will get you started.
Ryan Bates has also produced an incredible amount of Rails 3 screencasts over on Railscasts.com. Ryan has been producing Railscasts for over 3 1/2 years, isn’t that crazy?
There’s also a few good free screencasts over on Teach me to Code by Charles Max Wood.
Keeping on the Edge
If you find yourself wondering how to keep up with all of the newest features / libraries for Rails 3, both the Ruby5 Podcast and the Ruby Show are going strong. Don’t listen to audio? It doesn’t matter, just subscribe to the Ruby5 RSS feed and get links with descriptions to all the newest libraries, tutorials, and more. You might also want to checkout Peter Cooper’s new Ruby Weekly, a Ruby email newsletter.
Need to upgrade a big app to Rails 3?
Jeremy McAnally’s Rails 3 Upgrade Handbook PDF is just $12. There’s also a few paid screencasts for the upgrade over on Thinkcode.tv and BDDCasts.
Need a Book?
There’s a bunch of books that will be coming out after the release, most of which you can start reading now. The Rails 3 Way by Obie Fernandez, Rails 3 In Action by Ryan Bigg and Yehuda Katz, Beginning Rails by Cloves Carneiro Jr and Rida Al Barazi, and of course the Agile Web Development with Rails:fourth edition by Sam Ruby, Dave Thomas, and David Heinemeier Hansson.
In conclusion
No more complaining about lack of good documentation! Seriously. If you want even more Rails 3 content, check out the blog post by Kevin Faustino on 34 Ruby on Rails 3 resources to get you started.
Thanks a bunch Gregg!! All in all it´s quite good amount of documentation available! Don´t forget www.railsdispatch.org – there´s more stuff for the visual learners ;)
Funny how Rails 3 is mentioned in every section except the API Docs, which is what people traditionally think of when you say Documentation. In my experience, the API Docs have been very poorly maintained in the move to Rails 3. Case in point, no API Docs for the new router.
http://edgeapi.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Base.html
I brought up the awesome documentation in Rails 3 in my recent post. AR::Base has something like 3 lines of comments for every 1 code! http://bit.ly/c3RH6R
Is there a good place to look for a thorough overview of the javascript/ajax/ujs/etc changes (drastic changes, I think) that have been made for rails3?
I found a bunch of blog posts but a lot out of date, and none that seemed truly exhaustive of all the changes…ie, how do I do :success and :failure callbacks?, what files do they go in? do I modify rails.js? do I add to application.js, etc…
If your users are complaining you have poor documentation, you have poor documentation. You probably shouldn’t assume that they are wrong.
@Sam: I think it´s just that not everybody knows about every available resource for R3. As you can see there´s already detailed documentation available… I´m sure it´s more than enough for a new project to start, isn´t it?! Come on…
@Chris Griego I have actually been very busy updating the API docs in the past week. As you can understand there is a lot of ground to cover, so we’re far from there yet, but getting better every day. You can check my, and others’, progress at github.com/lifo/docrails. If you want me to focus on one particular area, drop me (tilsammans) a note on github. I have added the router docs to my TODOs now.
Chris, I just checked and the new router is explained in great detail at http://edgeapi.rubyonrails.org/classes/ActionDispatch/Routing.html. Is this what you were looking for or do you really need the Mapper::Base class documentation specifically?
There are enougth comments in the rails code to understand how it works.
I have been forced to use Django for a given project, believe me, Rails has greate documentation…
It always may be better, but there are enought to do great things.
The Rails Guides are great but it’s probably worth noting that they are a work in progress and not fully updated to Rails 3. For example, the new “validates” syntax for models is not mentioned, so I always have to look up the syntax on this blog post: http://omgbloglol.com/post/392895742/improved-validations-in-rails-3
To master Rails one needs to know Ruby and the best place to learn the language is at http://rubylearning.org/
People will always moan, particularly bitter people like me.
However, I have to agree, the docs are awesome. I’ve largely got away with just using API docs and occasionally use things like ASCIIcasts just and blog posts when I need to brush up on learning new features.
Rails has lots of good examples, unlike Java, where I loath the lack of decent examples and the bland waffle-fulled nature most Java API docs seem to have. (C and C++ can be bad, but I have to say I find Java far worst!)
Thanks for all the links, there were a couple in there I didn’t have yet :)
Which theme was TM used in railstutorial.org? Thx :)
The point is that there is (at least in my knowledge) no central place where the links to good (and not outdated) documentation pages are collected. I often got links to pages, for example to railstutorial.org, from Ryans railscasts or more or less randomly in blogposts if i search some topics with google. It is a good idea if on rubyonrails.org would be a managed documentation/tutorial catalog. Surfing through tons of blogposts for some tipps and references isn’t satisfying and maybe that what someone means if he/she says “Rails has a poor documentation”. The API docs are great, comprehensive and with a lot of examples.
And also a german Rails 3 book is available: http://rails.spider-network.net
;-) Michael
pertamax gan!!
Congratulations guys, now spend 200 hours to upgrade :(
woow, this is sounds cool, i am going to buy the PDF
Is there a comprehensive guide/documentation of Arel somewhere in all those links? I would like to see more complex examples than those in the RailsGuides.
I just installed Rails 3.
The following gems fail when gem tries to produce their documentation:
No documentation is produced and no error messages show up. I enforced the production with “gem rdoc”, but without success. Gem behaves, as if there is no documentation at all: rails has no documentation, railties has, but the gem specification says, it has not, and bundler uses incompatible markup and file extensions. Will this be fixed in future releases?
I am using ruby 1.9.2 and rubygems 1.3.7.
Is there any way to access the old Rails guides? All the guides at ‘guides.rubyonrails.org’ seem to cover only Rails 3 now.
There is also the free Rails 3 in a Nutshell book. I’m not sure how up to date it is.
http://rails-nutshell.labs.oreilly.com/
+1 for link to old Rails guides and API.
Old guides (or at least those for 2.3.8) are accessible at: http://guides.rubyonrails.org/v2.3.8/
I wish Java APIs and frameworks were as “poorly” documented as Rails’...
As someone who came over from PHP about 3 months ago, Rails documentation is good, but the fact that it’s distributed among several different (mostly unconnected) sources is frustrating. I often wind up Googling.
I’ve always considered PHP’s clear, quickly-accessible documentation (including community comments) to be among its greatest selling points. Being able to simply type ‘php.net/{function_name}’ in your browser is awesome (e.g. http://php.net/md5, or even if you get it wrong: http://php.net/md4).
Thanks, Richard, for the link to 2.3.8 Guides. Why is there no link (that I can find…) on http://guides.rubyonrails.org/ ?
Thanks for information!
No offense intended, but web pages like “34 Ruby on Rails 3 resources to get you started” just confirm that Rails is not well documented. For a well documented software product, one does not need 34 resources to get started. While this is great that many Rails books, tutorials, blogs etc. are available, this still cannot replace a complete reference manual, which Rails is leaking at this point. And I think this is what most users are complaining about.
Anyone looking for the old API docs can find them at …
http://api.rubyonrails.org/v2.3.8/
www.railstutorial.org/book was the best resource I have come across for learning how to use rails. It’s absolutely great!
Anyone looking for the old version (2.3) of the Rails Guides you can access it in the following URL:
http://guides.rubyonrails.com
the guides of the 3.0 version are in:
http://guides.rubyonrails.org
before I know this I made an application to browse and download (zip format) these two versions, you can access it in:
http://railsguides.heroku.com
Thanks.
It has great documentation, but none of it is here. Let’s take the subject of upgrading to 3.0-
anyone ever seen a working example of that process anywhere? Everything I’ve tried-including McAnalrape’s utterly worthless little plugin—has left me with nothing but a busted app that rake no longer recognizes, so starting a new one from scratch seems to be the only plausible option. Sounds great to me.Greg you are right, Rails 3 has an enormous amount of documentation for an Open Source project, however I would imagine that a newcomer to Rails would be put off by the amount of noise returned from Google searches and would get the impression of a lack of documentation.
I think the rails community needs an official source of docs and tutorials, to replace the current fragmented approach.
Rails has Good documentations for the new users that lasts for about the first 5 minutes but for anything beyond the rails guides you have bad documentation.
And Gregg
You are making a classic programmer mistake and assuming that your users are stupid. In this case they definitely are not. If they say you have bad documentation you need to listen and find out what they think is bad not just assume they are wrong.