A Ruby and Rails bibliography of sorts

"What book should I get?" seems to be one of the most popular questions on the mailing lists for both Ruby and Rails. I like to think that I stay on top of the Ruby and Rails book market, and so I thought I'd prepare a few bibliographies or curriculums or, if you like, big fat lists of books. I suggest following these in order for the most part, but if you're wild and crazy, feel free to ignore that.

Note: The title links are affiliate links; if you don't like that, then the links provided after the information are non-affiliate links.

Based on skill level

No programming experience

1. Learn to Program by Chris Pine

   
   

   This book walks you through the fundamentals of programming using Ruby. It's a great start to programming if you're ultimate goal is to learn Rails or simply to use Ruby. (link)

   
   



2. Beginning Ruby by Peter Cooper

   
   

   A slightly higher level read; it serves as a good basis for learning and as a nice reference. (link)

   
   



3. The Ruby Way by Hal Fulton

   
   

   This book is one of the very few books out there that teaches you solid, idiomatic Ruby. Highly recommended once you're comfortable with the basics. (link)

   
   



4. Ruby for Rails by David Black

   
   

   David does an excellent job of walking you through Ruby, and his section on dynamic programming is the best I've ever read. It's an excellent read if you're working towards Rails. (link)

   
   

Moderate programming experience

1. Learning Ruby by Michael Fitzgerald (link) or The Humble Little Ruby Book by Jeremy McAnally (me)

   
   

   I suggest these two because they're slim volumes; you don't need a lot of coddling if you already know the basics of programming. Most of your questions will not be "How do I do (x)?" but "How do I do (x) in Ruby?"

   
   



2. The Ruby Way by Hal Fulton

   
   

   This book is one of the very few books out there that teaches you solid, idiomatic Ruby. Highly recommended once you're comfortable with the basics. (link)

   
   



3. Ruby by Example by Kevin Baird

   
   

   A good look at Ruby through examples; it's a nice reference that's a little more practical than the cookbooks for the most part. (link)

   
   

Advanced programming experience

1. The Ruby Way by Hal Fulton

   
   

   You don't need any coddling: "Just show me the Ruby way and shut it!" (link)

   
   



2. Ruby Cookbook by Lucas Carlson

   
   

   O'Reilly's cookbooks are a great reference once you know the language well enough to apply the recipes. (link)

   
   



3. Ruby in Practice by Jeremy McAnally and Assaf Arkin

   
   

   My other book. :) It's a "higher level" cookbook for bigger "businessy" (technical term, I know) topics. Learn about practical topics like databases, reporting, automating communication, and so on. Also has a nice introductory section on some advanced Ruby topics. (link)

   
   



4. Programming Ruby by Dave Thomas, Chad Fowler, and Andy Hunt

   
   

   The "tome" of Ruby programming. I find it's teaching methods hard to get through unless you already know programming well, but it's incredibly useful as a reference. (link)

   
   

Based on role or task

The System Administrator

1. Practical Ruby for System Administration by Andre Ben Hamou

   
   

   Learn just what you need to know to start writing Ruby scripts. Not a comprehensive introduction, but still useful for those who don't plan on developing any heavy duty applications with Ruby. (link)

   
   



2. Everyday Scripting with Ruby by Brian Marick

   
   

   Another "just enough Ruby" book targeted at testers and sysadmins. It's a great little manual (I own a copy myself). (link)

   
   



3. Ruby Cookbook by Lucas Carlson

   
   

   Useful for looking up specific topics, and you can pick up a few useful techniques from it, too. (link)

   
   



4. Programming Ruby by Michael Fitzgerald

   
   

   It's always nice to have a quick little reference for a language's syntax. (link)

   
   

The Java Guy

1. From Java to Ruby by Bruce Tate

   
   

   Primarily aimed at managers, it can still give you either (a) a nice volume to give to your manager or (b) some good information to arm yourself with if you foresee a struggle with Ruby adoption. (link)

   
   



2. Rails for Java Developers by Stuart Holloway and Justin Ghetland

   
   

   A great book about Rails targeted specifically at Java developers. (link)

   
   



3. The Ruby Way by Hal Fulton

   
   

   Learn the Ruby way of doing things and learn it right the first time. (link)

   
   

The PHP Guy

1. Learning Ruby by Michael Fitzgerald (link) or The Humble Little Ruby Book by Jeremy McAnally (me)

   
   

   Again, the smallest Ruby books that are good because PHP guys probably won't be as interested in learning Ruby as they are learning Rails.

   
   



2. Rails for PHP Developers by Derek DeVries and Mike Naberezny

   
   

   This book is a long way off (February 2008), but it looks like it should be a great introduction to Rails targeted at migrators from PHP. (link)

   
   



3. Agile Web Development with Rails by Dave Thomas and David Heinemeier Hansson (and contributors)

   
   

   The "official" Rails book; it's a good introduction to Rails, especially if you're familiar with Ruby. (link)

   
   

To Learn Rails

After learning Ruby

1. Agile Web Development with Rails by Dave Thomas and David Heinemeier Hansson (and contributors)

   
   

   Probably the best book on Rails; at least useful as a reference if you hate the API documentation. (link)

   
   



2. Rails Recipes by Chad Fowler

   
   

   The best Rails cookbook that I've found. The O'Reilly one is nice, too, but I prefer Rails Recipes to it. (link)

   
   



3. The Rails Way by Obie Fernandez

   
   

   Think The Ruby Way but for Rails. I know Obie to be a great Rails developer (and he works at Thoughtworks!), so I'm sure this will be good when it's released November 20th. (link)

   
   

While learning Ruby

1. Ruby for Rails by David Black

   
   

   David does an excellent job of walking you through Ruby and into Rails. (link)

   
   



2. Programming Ruby by Michael Fitzgerald

   
   

   Just in case something slips your mind. (link)

   
   



3. Agile Web Development with Rails by Dave Thomas and David Heinemeier Hansson (and contributors)

   
   

   The official Rails book; pair this with the API documentation for Edge Rails for maximum effect since a lot has changed. (link)

   
   



4. Rails Recipes by Chad Fowler

   
   

   The Pragmatic Programmer's Rails cookbook; very nicely selected recipes in my opinions. (link)

   
   



5. The Rails Way by Obie Fernandez

   
   

   Think The Ruby Way but for Rails. (link)

   
   

For advanced Rubyists

To hone your Ruby...

1. The Best of Ruby Quiz by James Edward Gray, II

   
   

   If you haven't ever done a Ruby Quiz, then you should. I used to try to keep up with them every week, but I've lost track of it in recent months. This book is a compilation of some of the best Ruby Quiz quizzes. (link)

   
   



2. Ruby in Practice by Jeremy McAnally and Assaf Arkin

   
   

   My other book. :) It's a "higher level" cookbook for bigger "businessy" (technical term, I know) topics. Learn about practical topics like databases, reporting, automating communication, and so on. Also has a nice introductory section on some advanced Ruby topics. (link)

   
   


3. I'll take any suggestions for this section you might have...

To hone your Rails...

1. Ajax on Rails by Scott Raymond

   
   

   A great book on writing AJAX applications with Rails; I just got around to reading this recently and thought it was really helpful to workout some of the grey areas. (link)

   
   



2. Rails Cookbook by Rob Orsini

   
   

   The O'Reilly Rails cookbook; a really comprehensive volume. (link)

   
   



3. Advanced Rails Recipes by Chad Fowler and Mike Clark

   
   

   The recipe list for this book due out on December 15 looks great; I really look forward to seeing if this is as good as the first one. (link)

   
   

To be a more well-rounded Ruby developer

1. The Practice of Programming by Brian Kernighan and Rob Pike

   
   

   Brian Kernighan (of K&R/The C Programming Language fame) teams up with Rob Pike to write a really, really good book on good practices for programming. This offers a really wide scope introduction to a lot of topics, and it's something I recommend that you read first if you're not a very well rounded developer. It's based on C/C++ but the concepts are easy enough to translate to Ruby for the most part. (link)

   
   



2. Beautiful Code edited by Andy Oram and Greg Wilson

   
   

   A collection of essays from a lot of computer science luminaries (including Matz, the author of Ruby). I'm reading through this currently and it's shaped up to be a great collection of essays on writing...beautiful code. (link)

   
   



3. The Pragmatic Programmer by Dave Thomas and Andy Hunt

   
   

   This book was written 8 years ago but everything inside still has value. This is a must have for any self-respecting developer. (link)

   
   



4. Write Great Code: Volume 1 (link) and Volume 2 (link) by Randall Hyde

   
   

   I just started these books, but I think they're going to turn out to be excellent overviews of the structure of computers. So many times we get caught up in our abstractions, we forget there's a machine under there, and our code would probably work better if we thought about it once in a while.

   
   

To be a more well-rounded Rails developer

1. RESTful Web Services by Leonard Richardson, Sam Ruby, and David Heinemeier Hansson

   
   

   An excellent book on REST, with examples in Ruby and others. I'm about half way through and it's cleared some of the murk away from REST for me. (link)

   
   



2. Prioritizing Web Usability by Jakob Nielsen and Hoa Loranger

   
   

   The standard book on web usability. Developers typically like to push concerns such as usability off to designers, but it's also our responsibility to create usability compliant markup. This book is more or less geared towards design, but it will work until the Pragmatic Programmers can get their usability book out the door. (link)

   
   

And best of all...

The $0 Ruby and Rails curriculum

1. _why the lucky stiff's poignant guide to ruby or The Humble Little Ruby Book or The Little Book of Ruby

   
   

   Three free Ruby books, from craziest to least crazy. Some people prefer _why's style, others hate it. Take your pick. :)

   
   



2. The Pickaxe (version 1)

   
   

   A free version of the Pickaxe. This version is based on Ruby 1.6 (we're at 1.8.6 now), but most of it still holds true.

   
   



3. Ruby Doc

   
   

   The Ruby API documentation is a great reference; this is more up to date than the reference in the free Pickaxe.

   
   



4. Build Your Own Ruby on Rails Web Applications

   
   

   Sitepoint's Rails book is free for a little while longer, so you'd better grab it while you can!

   
   



5. The Official Rails API or The Edge Rails API provided by Caboose

   
   

   The Rails API documentation is more up to date than the Rails book, and the Caboose version of the documentation is generated often to keep up with recent changes in Edge Rails.

   
   

And that's it! Let me know of any suggestions you have and I'll consider adding them.

My book (Ruby in Practice) now in MEAP/Early Access/beta edition/whatever

Lots I need to blog about, and so little time and energy to do so! For this entry, though, I'll just mention that my book Ruby in Practice is now in the MEAP (Manning Early Access Program). So that means you can grab a PDF copy of the 2/3 of the book we have done (1/3 is posted now; next 1/3 should coming any day now) and help me edit it, work out bugs, insult me, and/or, hopefully, get something out of the content.

Now that you've heard me beg for you to buy it, go do it!

dcov 0.2.1 Released!

I just pushed a new version of dcov, the Ruby documentation analyzer, to the Rubyforge servers. This version adds a new analyzer setup and quality analysis. The new analyzers go from crazy scripts that pick through the guts of dcov and do a lot of stuff to slightly abstracted but much prettier scripts that use a nice DSL. For example, this is from the quality analyzer:

documentation_for_methods do |the_documentation|
  the_documentation.must "document all parameters." do
    param_names_for(the_documentation.token).each do |param|
      the_documentation.token.reporting_data[:parameters_without_coverage] << param[0] unless the_documentation.token.comment.include?("+#{param[0]}+")
    end if the_documentation.token.params
  end
end

If you can't tell, I based the aesthetics of the analyzers on RSpec specs. They are nicer, but they should probably reveal less of the guts of dcov.

The basic analyzers that come with it work, but they're really supposed to be examples for you to work from (hence the nicer syntax for analyzers). Everyone has different documentation standards (placement of elements and units to be documented) with varying degrees of analness (some people aren't allowed to you direct address, for example). The included analyzers can give you a very basic idea of how your documentation is doing, but I'd like to see people develop new quality analyzers...possibly contributing back? :)

Enjoy and please e-mail me, IM me, or comment with any bug reports or problems. Or you can use that silly bug tracker thing.

VOTE FOR US: Conduit (Our Rails Rumble application)

Visit here and vote for us.

In case you missed it, here's a little description of Conduit:

Imagine this scenario: you’re working hard and need to send a message to your Marketing Team, making sure they get it as soon as possible. You could send it via e-mail, SMS those who rarely check their e-mail, and hunt the rest down on IM. What a hassle! Wouldn’t it be much easier if you could send a message from a centralized place and have them all get it on their favorite, most frequently checked mode of communication?

Introducing Conduit, a centralized communication hub. Users send messages over “channels” (such as the ‘Design Team’ channel or ‘Friends’ channel) and the users subscribed to that channel receive the message on their favorite mode of communication, be it e-mail, IM, or whatever. Some have called the idea “Twitter for businesses.” Others have called it “Genius.” We call it “our Rails Rumble application.”

The app isn't totally complete (and probably isn't fully functional), but we're working on getting it up and completed at http://www.conduitapp.com/. Look there for the newest updates!

Oh, and VOTE FOR US (or at least our idea)!

Rails Rumble, RubyEast, and the Ravishing, Regal Regalia of the Red Robin

This weekend a couple of friends and I competed in the Rails Rumble, developing, what I think to be, a solid product (even though it currently has quite a number of rough edges). We call it Conduit, a communication application that lets you send messages from one interface and have them delivered over the medium of the receipients' choice (currently, AIM, IRC, e-mail, SMS, Campfire, Jabber, and Twitter are available). The basic mechanism is that you create an account, invite users, create channels (such as "Design Team" or "Beta Testers" or "The Wife's Family"), the confirmed users subscribe to these channels, and then the messages sent over those channels are doled out to all subscribers over their preferred communication medium. So if you send a message to your Design Team channel, Mike can get it on AIM, Ralph over e-mail, and you know Alice spends half her day on Twitter. Go ahead and vote for us when the voting opens on Wednesday!

Let's hope we win. We won't find out, though, until RubyEast in Philadelphia at the end of this month. I'll be speaking, giving The Humble Little Ruby Talk, an introduction to Ruby. This will be followed up by Amy Hoy's introduction to Rails, so if you're a Ruby newb or a Rails neophyte, you should go register up. Even so, if you're a seasoned vet, a lot of the talks look really interesting. Head on over to the conference site and take a looksie at the talks and maybe even the registraiton page.

Thoughts on documentation: Conventions

While working on the Rails Documentation Project, it's been interesting to see the veritable array of documentation styles and conventions present in a single (albeit, open-source and slightly heterogeneous) code base. Sometimes the options hash is documented fully, other times it's not. Sometimes they document it once at the head of the class, sometimes it's for every method. Sometimes they put one sentence that is essentially a humanized method name (e.g., check_box_tag = "Makes a check box tag"), sometimes they include an entire essay about the method. Of course, it isn't unique to Rails nor open source, but Rails is the first project where I've combed through the documentation from front to back (and, of course, side to side, because you know how I work it).

But what about conventions? One of the things I've learned from those who do "technical writing" as a career is that they typically have quite rigid standards, styles, and conventions to follow when writing. Whether it's a style guide that indicates which case of a verb to use in every instance or a specification that dictates the structure of every piece of documentation, the "real world" of technical documentation isn't as free wheeling as we like to treat it, and this cavalier treatment of documentation is one reason that Rails (and, to an extent, Ruby) isn't taken seriously by a large portion of "corporate" entities. First question anyone will ask when considering using a technology is, obviously, "How do you learn how to use it?" Obvious answer: the documentation (less obvious, blogs, mailing list, talking, training, and so on, but the most obvious and useful answer is the documentation). If your documentation looks like a hodge podge of documents that have been scraped from a blog, then how can you expect anyone to take it seriously? Compare that with the documentation for the .NET framework, Python, or a lot of larger Java projects. They have conventions, and I think we should take a careful look at what they do with them.

First, they enforce documentation for every piece of code. Nothing goes in the framework or project that isn't documented. Granted, some things don't need documentation (thanks :nodoc:!) because they don't need to be used by anyone but the framework, but anything that is exposed and usable, should be documented. I'm using the term documented in a very specific meaning here: not the loose context that people consider "documented." Documented is not humanizing the method name or stating the obvious. Documenting is connecting what a functional unit of software does with how to make it do it. It is drawing the schematic for the builder. OK, I'm out of metaphors, but you get the idea: you're showing something hidden.

Now, this doesn't mean you need to pad your documentation with a lot of narrative. To the contrary, it's usually better if you don't. For example, my check_box_tag example earlier was a little unfair. About the best you can do with narrative is something like, "Generates a checkbox tag (<input type="checkbox">) in a form" (and even then, that's a little more than needs to be said in most cases...). Typically you would reduce your narrative and explain in depth with examples, where you can reveal the underlying functionality in practice. For example, you could do...

Generates a checkbox tag (<input type="checkbox">) in a form.  Your options are :disabled, which if set to true, the user will not be able to use this input, while any other key creates standard HTML options for the tag. 

Calling check_box_tag 'accept' will generate a checkbox tag that will have the id of accept, and the value of 1: <input id="accept" name="accept" type="checkbox" value="1" />.

[And so on...]

OR, you could get a lot more bang for your word and do something like this...

Creates a check box form input tag. 

Options
- :disabled - If set to true, the user will not be able to use this input. 
- Any other key creates standard HTML options for the tag. 

Examples
  check_box_tag 'accept'
  # => 

  check_box_tag 'rock', 'rock music'
  # => 

  check_box_tag 'receive_email', 'yes', true
  # => 

  check_box_tag 'tos', 'yes', false, :class => 'accept_tos'
  # => 

  check_box_tag 'eula', 'accepted', false, :disabled => true
  # => 

Now the user can evaluate the method's functionality without a lot of verbosity, and see what the method does in real usage. This example-driven documentation style has been criticized, but I don't think you can argue with it.

Second, by enforcing standards, you gain usability. It's easy to flip to a piece of documentation and know how to find exactly what you're looking for. This is something that was a big concern for us when working on the Rails documentation because as the documentation stood before, many things could be placed in a disjointed manner (even in the same file or class). One of the best examples of documentation I found was Assaf Arkin's assert_select module. We were doing something very similar to what he was doing before, but we definitely took a few pages from his book and beefed up our standards. The options explanations were in the same place and formatted the same, the examples were always last, and every method or class had an introductory blurb with a general overview of what it did. Following a single convention all the way through makes it incredibly easy to find exactly what you want.

Third, by using a solid convention, it makes it easier to write and maintain. I think it's funny that Rails embraces conventions so much inside the framework that they haven't taken the same stance with its documentation. Having a simple set of conventions to follow would make the documentation so much easier to update. Change or add an option? Fix it in the options sections. Change a parameter? Change the parameters list. Totally change the way a method behaves...well, at least you'd have a template to start over with. :)

So, what sort of conventions do I use? In dcov, I check for a laundry list of obvious things in the standard quality analyzer:

• Everything must have examples


• All options hashes must be documented somehow.


• All parameters must be documented in some form.


• All default values must be explained.

These are obvious things, though, right? To really have a set of conventions, you need to dig deeper and get more specific. I'm a fan of tighter conventions rather than a loose style manual when it comes to this sort of thing, so here's the setup that I use in RDoc:

Introductory material goes here, where I explain the jist of the method and mention a few key parameters if I need to.

==== Parameters
* parameter  - Explains all parameters if the list can't be easily explained in the introduction.

==== Options
* option  - Explains all available options, possible values, and default values.

==== Examples
   # A few examples, documented in comments if possible
   puts "Howdy!"

I think this is a fair start for most Ruby code, but I'd like your input. Is it too verbose for most cases? Should it be rearranged or compressed?

The Ruby Hoedown starts tomorrow!

If you haven't gotten your ticket, bounce over to the conference website and register!  There will be good talks, good times, and free stuff!

Thoughts on Documentation: Quality

Recently I've been working on my Google Summer of Code project dcov (a Ruby documentation analyzer) a lot. It's basically broken into two large functions: analyzing your documentation and reporting on it. I don't have to do much on reporting (thanks Ruport!), but on the analysis side I'm basically making it up as I go. The first part of the analysis is quantity: is something documented? Right now, this works famously: it can give you a precise precentage of your functional unit documentation coverage. This is easy, of course, because all it has to do is check for the presence of a comment. The second part is quality, and that's where the analysis gets a little hairy.

There are no documentation standards for Ruby/Rails really (I'm working on an entry on this...so bare with me), and so I'm sort of left to my own devices when analyzing quality. The plan is to allow users to write their own analyzers and thus let them create their own quality standards, but it would be nice to include a "default" quality analyzer. The problem though is not what it should do, but how?

Quality is so subjective, that if we're to do a midline, objective analysis, a standard needs to be developed or some sort of criteria needs to be met. This entry is little more than a plea to you guys and gals: help me create one! What do you think makes good quality API documentation? I'll reconcile your responses into something workable in a future entry and that will become dcov's standard criteria set (until we decide to change it ;)). Here are a few of my ideas:

• Parameters should at least be mentioned.


• Options hash must be documented if present.


• Default values must be explained.


• A return value description should also be present, if there is a return value and it is not apparent.


• Examples! Examples! Examples!

Let me know what you'd like to see.

New blog...

I got tired of paying for a hosting service that only housed my blog, so I'm moving to Blogger.  I'll be posting more now that I don't have to worry about maintaining it... :)