small medium large xlarge

10 Sep 2008, 05:10
Brian Jones (3 posts)

I’m getting the feeling that reading this book is like being handed a fish rather than being taught how to fish. I see the working example and I can follow along but when I go to look for the documentation on the commands being used in the examples I can’t find the documentation. I see the API documentation on Rails ( Where, for example, is the ‘generate’ script documented? When looking at the scripts/generate file, it just loads other files which in turn are not documented.

Given this command (p80)…

ruby script/generate migration add_price_to_product price:decimal

Where do I find the documentation that tells me that I can use the ‘migrate’ keyword as well as the other tokens on the line? The same goes for this command:

ruby script/generate controller store index

I guess I’m just used to all the man pages in Unix/Linux and find it very frustrating how Rails is documented. This lack of documentation seems to plague virtually every book that I’ve seen so far that attempt to explain how Rails works.

10 Sep 2008, 12:06
Sam Ruby (634 posts)

Perhaps the problem is that the book isn’t organized as you expect it, or that you haven’t yet gotten to the right place in the book. Page 242 lists the scripts provided, and provides a brief description for each. A more full description is provided in the sections that describe that specific functionality (in the case of migrations, this would be chapter 16).

Given that all this information isn’t all in one place, it is entirely possible that something is missed. If so, let me know, and I’ll fix that.

It is possible that there would be some value in an appendix that consolidates this information. However, all that appendix would contain is “something like this”: . It will never be complete as “more generators”: are always being created.

10 Sep 2008, 12:23
Dave Thomas (390 posts)

And, just to add to Sam’s comment:

If you type @script/generate@ with no parameters, you get the list of generators. If you type @script/generate migration@ with no extra parameters, you get the parameters that @generate@ accepts.

10 Sep 2008, 15:19
Sam Ruby (634 posts)

I did not know that. That’s definitely going into the book! ;-)

11 Sep 2008, 01:01
Brian Jones (3 posts)

Ah! Exactly. Dave, where did you find this out? Or is this just ROR tribal knowledge? Sam, yes, that link (“something like this”) is what I was looking for. The page leaves me wanting more though.

I’ve read (somewhere) that the ROR community relies more on people reading the source code as the de facto documentation rather than writing formal documentation. This might work for the early adopters but I just cannot imagine how ROR will gain wide spread adoption without a much more serious documentation effort. I think a lot of the tutorials tell you how to do things but I get this feeling that people are left wondering what to do next. Were is the ROR body of knowlege, like the Perl “Camel” Book for Perl programmers for example. I knew when I started learning Perl 14 years ago that I could read the Perl documentation and find answers to my questions. There was a complete set of documented functions and language features that I could refer to to grow my understanding. Each new release of Perl just made the documentation even better. With ROR, the information seems rather scattered. I keep asking myself what do I really need to do to really learn ROR.

For example, to learn Perl (now) I would…

  1. Read the Learning Perl book. Write a few scripts.
  2. Get the Camel book and read sections for script areas I’m weak on. Start writing modules.
  3. Study data structures, module layout, and object oriented programming aspects of Perl. Start wring OOPs modules.
  4. Expand to CPAN to get modules written by other users for pieces I did not want to write myself. Include modules in my work from CPAN.
  5. Get the more “expert” level books on Perl to move into advanced subjects. etc.

What path should a programmer take to ramp up on ROR? It would be great if you could sketch out a “how to learn ROR” road map. For me, so far, it’s been:

  1. Read “The Ruby Programming Language” O’Reilly book
  2. Read “Programming Ruby” pragmatic programmer’s guide (beta book)
  3. Read “Agile Web Development with Rails” 3rd edition (this forum), follow the tutorial.
  4. Consult “The Rails Way” by Addison Wesley - So far this book has been a slow read and seems to dive into the parts without really giving me a feeling of context.
  5. Consult “Rails Cookbook” by O’Reilly - leans towards a focus on the parts, assumes knowledge of the whole but is a step in the right direction
  6. Consult “Advanced Rails” by O’Reilly

And mixed into all that, consult the Rails API on the web. This seems like a haystack of knowledge, so I don’t really know what pieces to read or focus on. Oh, and I have “Rails Recipes” too but that assumes the person is up and running with a working core knowledge base and the code is a bit dated now.

Consider this. A google for “ruby on rails” leads me to as the first search result. This site leads me directly to your book under “getting better” ( So, the default first stop people are going to take when trying to learn ROR is your book. It would be nice if your book could sketch out the lay of the land on how to learn ROR and get the root documentation. A number of the reviews of the ROR books on Amazon complain about the absence of information like this. (“After I read this book, then what do I do?” sort of thing.)

One of the things I’ve noticed too is that with programming by convention, there are A LOT of assumptions made regarding how things work (meaning what’s done for you by magic). Where are those assumptions documented and how do I learn how to intelligently override them? I don’t want to break all the conventions but I’ll need to know the advanced things when I develop more complex web functionality. The downside of coding by convention is that when I look at the code, I cannot connect all the dots. Yes, I see that it works, but I’ve no clue how or why because I can see why it works, the code that is really running is behind the scenes. It’s the same frustration new Perl programmers have when they see a Perl program operate on the $_ and @_ variables but those variables are not coded into the source explicitly, except in ROR, it’s an order of magnitude worse because there is so much more being done for you.

The know how seems to boil down to: 1. Show me a working example. Your book covers this. 2. Tell me everything that is being done for me behind the scenes in the context of the “big picture” MVC world view. I think this is the second half of your book as well as (3). 3. Tell me how to override and/or extend the default magic actions 4. Where do I find the first person (not second person) documentation on all those things so I can take it from there. This is where there seems to be a deficit in ROR in general.

This has been a bit of a ramble, I hope you don’t mind, just trying to help.


11 Sep 2008, 14:11
Sam Ruby (634 posts)

Like most complex questions, the right answer is “it depends”.

I can say that the only books I have read on the subject are PickAxe (your #2), and a prior edition of this book (#3). I do have a background in other languages, and your prior experience with Perl will serve you well. But it wasn’t until I actually started using the language and framework (and referring back to both books frequently) that I truly became comfortable in Rails. Blocks, and their importance to the Ruby language, in particular took multiple passes for me to fully grok.

Prior to signing on to contributing to this book, I rarely looked at the Rails source code.

This book does point you to early on… page 41. That being said, there are areas (such as configuration) that you won’t find documented there, nor even will you easily be able to find such in the code as much of this is dynamic.

While I have become largely self sufficient on Ruby (at least in terms of 1.8), and by that I mean I rarely need to refer back to the PickAxe book, I find that I continually need to refer back to this (AWDwR) book for guidance on Rails. And now that I’ve signed on as an author, I’m using the opportunity to add in “tribal knowledge” such as being able to specify the gem version on the rails command line (section 3.5, page 37).

12 Sep 2008, 16:23
Bharat Ruparel (148 posts)

Brian, You may want to look at the Advanced Rails Recipes book. As I am beginning to program in Rails professionally, I find myself turning more frequently to the Rails Way, Advanced Rails Recipes, and Agile Web Development (particularly the later in-depth chapters on Active Records for example). But I understand your frustration. There does not seem to be a smooth transition from knowing and learning basic material to the real world professional material in general. Chad Fowler’s Rails Recipes book is pretty good too, but is a bit outdated. Yet another book that I found that helps answer some of the questions like you are asking is David Black’s Ruby for Rails Developers, highly recommended but a bit obsolete. That is the nature of the beast. Rails moves too fast and you can more comfortably keep up after you acquire some “how to fish” skills. My approach has been to read and hack widely and then dive-in. I find myself using Google extensively to research more specific questions, so Google is an indispensible tool. If you get to maintain the code written by more experience Rails developers then it can be both a very frustrating but a very quick ramp up to knowing Rails at the same time. You will have quite a few highs and lows though. Hope this helps. Bharat

You must be logged in to comment