codahale.com٭blog

Improving the Rails Experience, Part 2: It’s So Hard To Find Good Help These Days

Read Part 1: Help Vampires, Mogwai, and You.

To recap, Amy Hoy points out in her article Help Vampires: A Spotter’s Guide that there has, of late, been a huge influx of Rails beginners bombarding IRC channels, forums, and mailing lists with questions they could answer themselves. First off, I think this is less an indicator of the average beginner’s intelligence (I mean, they’ve got enough smarts to choose Rails, right?) and more an indicator of how spectacularly munged the Ruby on Rails documentation is.

Imagine you’re a programmer

Let’s say you’ve a, I dunno, Java or PHP programmer. You have some evil programming ways built into your fingers’ muscles already, but this Ruby on Rails thing looks fun, so you give it a shot. You get Ruby and Rails installed okay, and you decide you’re going to build a hello world blog app for kicks. You come across a chunk of code which puzzles you. Where do you go for help?

Better question: where don’t you go?

Okay, so we’ve got the API docs, some manuals, the goddamn wiki, any number of blog articles, ranging from absurdly antiquated to the vaguely useful, and various books. Plus you can build the rdocs yourself using rake apidoc, unless you’ve got Rake 0.7 installed, in which case you get a useless error message.

Oh, wait, was that a Ruby question?

Well, there are the docs, the other docs, the craziest goddam thing you’ll ever read about programming, the pickaxe book, assorted miscellaneous, the trash heap of history, ri (if you’ve installed it), and a bunch of crap in Japanese which probably explains everything.

To ask a newbie to sort through all of this nonsense is cruel, but nonetheless there it is. It’s also worth mentioning that none of these resources are searchable, unless you use the little-known site:api.rubyonrails.org modifier for Google, Yahoo, or MSN. And god help you if you’ve got a question about the tall grass…

The tall grass

Eventually, with Ruby/Rails documentation, you find yourself alone, in a field of tall grass with no horizon or landmarks to speak of. You can find your way back with the back button, but there are areas of Ruby and of Rails which are almost completely undocumented.

For example, SOAP. If you want to use another application in your Ruby/Rails app via SOAP, the only recourse of action you have is either bugging folks with obvious questions (”How in sweet hell do I use SOAP?”), staring blankly at the non-existent documentation, or buying a pre-release copy of Enterprise Integration with Ruby. I recommend the latter, since the first two didn’t work for me at all.

So how to improve this situation?

Pre-baked web sites are for sissies

I think it’s ironic (read: sad) that the Rails community, which is the bleeding edge for advancing the state of the art of web applications, relies almost entirely on RDoc files to explain how their code works. How to build a web app with AJAX, web services, etc., as expressed in static HTML files baked on release by a small script scanning for comments. And that’s not nearly Web 2.0 enough. But seriously, RDoc doesn’t meet our needs for three reasons.

Info-dump != Usable

First, it doesn’t mesh with how humans find information. As a browse-only interface, RDoc doesn’t allow me to, say, search. I can’t narrow the information presented to me in any meaningful way, and I’m limited to scrolling through endless lists of modules, classes, methods, and files. A fundamental necessity of any next-generation documentation platform is the integration of searching and browsing. Worse, the standard RDoc template (and the template used at api.rubyonrails.org) uses frames, making it impossible to use the browser “find text” feature. The remaining option is scrolling through an alphabetical list of methods, thinking “Hmm… probably starts with ‘u’…”

Info-dump != Useful

The second reason RDoc falls flat is that it doesn’t mesh with how people use information. Unless I specifically create a README file and then include that file in my RDoc build statement, the readers of my documentation get no viable overview of my code. The structure of the code is not necessarily the structure of how the code is meant to be used. It’s important to make the distinction between trying to understand how code works and trying to understand how to use code. They’re by no means mutually exclusive, but they’re not the same thing.

Think about, when writing the RDoc statements for a module or plugin you’ve worked on, how many times you’ve used the #:nodoc: or #:doc: tags on a method. Why shouldn’t all the methods in your code show up in the documentation? Because some of them are internal-only, and only need to be understood by people working in that code itself. Abstraction! For any interestingly complicated piece of code, I think it’s fair to say that if your users need to know about every single method in the entire thing you’re doing something wrong.

RDoc’s great for internal documentation, but crap for external documentation. And it’s external documentation that people need in order to learn how to use Ruby and Rails.

Info-dump != Interesting

The third and final reason why we should be looking outside of RDoc is that it doesn’t offer any possibility for interactivity. There’s a reason that some of the best Rails documentation is found on blogs. Leaving a comment is easy, getting a question answered is easy, and it’s easy to draw attention to a cool howto: link to it. (hint, hint) Nothing equivalent is possible with RDoc; in fact, given its propensity for frames, it’s hard to link to anything at all.

But what about the wiki?

The wiki is broken.

Every time I visit the wiki it gets bigger and bigger and more useless and useless. Wikis are the documentation equivalent of a big sign saying “Oh hell, we don’t know, either. Put either actual information or that picture of something chasing a kitten here. P.S.: Spam us.” They are a last-ditch approach to something which really should be structured. They are the abdication of responsibility for providing information.

“But look at Wikipedia,” you might say. Yes, look at Wikipedia. See how they have a bunch of people working as editors? Yeah, the Rails wiki doesn’t have that. As far as I can tell, it doesn’t have anything but a few brave, frustrated souls drowning in a deluge of wikispam. There is no architecture to the wiki beyond a rough outline, and the content ranges from spectacularly useful to outdated or just plain wrong, and every push for better organization seems to be met with the continued apathy of random programmers, trolls, and spambots.

Instiki (i2), the platform that the Rails wiki runs on, is nowhere near capable of handling that amount of information, that number of authors, or that public of a site. Searching the wiki is impossible, as Google indexes not only the current version of a page (i.e., the actual information) but also various past versions and even the page you get when you edit a page. (Yes, folks, there is a good reason why you put stuff like that behind a POST request.) It’s an application designed to be small and simple, but the Rails documentation is anything but.

We should reuse a lot of the content on the wiki, but as far as platforms go, the wiki is utter rubbish.

No, we need an actual solution

I’ve laid out three design goals here–findability, context, and interactivity–which I think are crucial to any next-generation documentation platform. I’d like to add a fourth design goal, and it’s a bit more abstract: we should be helping our users kick ass. To paraphrase Kathy Sierra, the documentation should be the straightest line between the code (Ruby, Rails, a plugin, whatever) and the user being able to get her application working. But, y’know, kicking ass.

The overview

The basic unit of our new documentation platform is not the .rb file. It’s not the module, the method, or the class. It’s the page. The first thing the users sees when she goes to the documentation is an overview of the capabilities and usable structure of the code. By usable structure, I mean the structure as it’s used, not as it’s written; the structure the user needs to know about. Diagrams would go a long ways to give the user an overview of the code, but ultimately it comes down to the written word to convey information.

This is not to say that method listings won’t be there–the user should be able to drill down into the code as far as she’d like–but that putting them front and center is counterproductive. The user needs to know about how the entirety of the code works as much as she needs to know the parameters for a particular method. Think about this: can a person be a good Rails programmer without:

1. Knowing how to call link_to?
2. Knowing what happens between a user clicking on a link and the code inside an action being executed?

The Rails documentation does a great job of explaining how something works, but its scope is limited to the modules laid out by the Rails devs for easier development and maintainability. How does ActiveRecord interact with ActionController? Well, that happens between modules, so RDoc can’t really handle it. Unfortunately, this kind of thing is Ruby’s bread-and-butter, and it’s critical operational knowledge for programmers.

Rails has a great elevator pitch (”Ruby on Rails in an open-source web framework…”), but it needs more. There should be explanations of Rails for variable amounts of time: 30 seconds, 5 minutes, 30 minutes, 1 hour, etc., each of which would go into progressively more detail. Eventually, these would be the official walk-throughs, at which point we could have a mandatory-ish hour or so of reading which would cover 80% of the newbie questions and provide them with the resources to find the answers to their questions.

The search box

Any modern documentation platform must be searchable. Plain and simple. Full-text, modern boolean operators, decent ranking, and well integrated into the existing browsing scheme. Handing searching off to Goggle is, again, the abdication of responsibility for helping users find what they need. For God’s sake, people: PHP.net has a usable search functional and we don’t. That’s shameful.

Another aspect of findability is the ability to bookmark pieces of information. I want to be able to bookmark the documentation for url_for or ActiveRecord validations without having to right-click a link, copy the URL, create a new bookmark, enter the name, paste the URL, and click Save. I want to be able to keep a shortlist of things I keep forgetting, so looking it up again is two clicks away.

The interactivity

Interaction is a huge must, and right now the only aspect of Rails/Ruby documentation which is interactive are blog articles. (I don’t count the wiki, since it’s interactive like putting a message in a bottle.) Users should be able to comment on and rate any piece of information in the documentation. Feedback is crucial.

User-created documentation should include recipes, gotchas, and code snippets. These should have an explicit link to the version of the code to which they are applicable (e.g., works with 13.0-1.0, dunno about 1.1 or Trunk), to keep outdated advice from continuing (see: Rolling With Ruby On Rails).

Are we not ass-kickers? We are Rails.

Back to our original problem: hoardes of newbies, bum-rushing IRC channels, fora, and mailing lists all asking the same questions.

I think it’s a testament to the simplicity and humanity of Rails that, even with just a handful of books and some robot-generated websites, people are picking up Rails in such numbers and with such verve. Once you start to understand how Rails works, its synatx and structure insinuate themselves into your brainmeat, until just about any other architecture seems like a huge hassle for a very small reward.

But I also think it’s time that we step up to the plate and actually try to put some weight behind this community. We’ve got an insanely good language, and a redonkulously sweet framework, so why is our documentation so crusty?

Next up in my overly preachy series on how to improve the Rails experience: why scaffolding needs to sit down and shut the hell up.

This entry was posted on Sunday, March 26th, 2006 at 7:34pm and is filed under Programming, Ruby and Rails. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.