Out of date documentation

Rails moves fast, and it's very common to see out of date documentation. During my recent walk-through of Agile Web Development with Rails, 3rd edition, I encountered a problem where Rails 2.3.8 handles Session configuration differently from what the book describes.

That is normal with Rails. By the time documentation is written, and especially once things are in print, Rails has already moved on. Rails developers need to know this ahead of time and become comfortable with reading Release Notes, digging through the source, and checking various websites (Stack Overflow is a pretty helpful site for developers).

Simple Heroku Add-on with Sinatra

I was playing around with creating Heroku add-ons, and the tutorial page is helpful, but the examples provided are somewhat complex.  I've created a project on GitHub with a complete sample Sinatra app.  Some particular notes:

1. to_json is not in Sinatra, so you'll need to pull in the json gem
2. I include a config parameter to demonstrate how to nest parameters properly; that's not strictly required, but any practical add-on will need that
3. The requirement for kensa to use  HTTP Basic Authentication seems odd to me, but the Sinatra application simply loads in Rack::Auth::Basic and requires it for every URL handler.

Stay tuned for other sample Heroku add-ons.

Chapter 4 - things I missed the first time around

When I first read Agile Web Development with Rails (AWDWR), I skimmed over link_to. That's hard to believe now, but I can clearly recall coming to some Rails code and wrestling with link_to. Additionally, ERB was a bit of mystery, too.

I strongly encourage those new to Rails to slow down in Chapter 4 and actually do the experiments at the end of the chapter.

Even though ERB is tried-and-true, some HAML, Markdown, Redcloth coverage would be useful in a third edition, at least as a footnote. It's probably worthwhile to add a chapter in the book to the topic, rather than overwhelm the reader during the first demo application, though.

Chapters 1-3

So I have a copy of the second edition (which is the current version), and it's pretty out of date, as it uses Rails 2.2.2. When I first read the book, 2.2.2 was reasonable, but trying to do Rails 2.2.X now is actually a bit difficult: Rails 2.3.5 or 2.3.8 is probably the oldest Rails anyone coming to Rails should try to use, whereas Rails 3 is probably too new to start with.

I know the Pragmatic Programmer folks are revising the book and hope to have the Rails 3 version published by the end of 2010. Obie's Rails 3 Way is available in Rough Cuts on Safari, and should be out early this Fall.

It's probably too much to ask that the 3rd edition mentions RVM, but we can always hope. That's what I'm using to do the coding from the book, and, I'm actually using 2.3.8, not 2.2.2.

Agile Web Development with Rails

While I've used Rails for a few years now, I thought it would be interesting to go back and re-read the classic Agile Web Programming with Rails, following along with all the coding, so I've scheduled some time in Google Calendar each day to do so.