My good friend Peter Dolan is up to his usual crazed hijinks. This time he’s writing a blog without words.
This is your brain on math, kids. It’s actually quite pretty.
The blog is dead! Long live the numblog! Long live doing seriously weird things to web pages!
(Mmm… whitespace…)
Leave a comment »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.
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?
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.
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…
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?
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.
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’…”
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.
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.
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.
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 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:
link_to?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.
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.
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).
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.
5 comments »Amy Hoy nailed it with Help Vampires: A Spotter’s Guide, plus she came up with cute little graphics to make her point. For whatever reason, I find cute little graphics incredibly persuasive.
I spent a week or so hanging out in #rubyonrails before getting tired of answering the same questions over and over again (or trying to explain why a question was unanswerable), and I think that part of the influx of huge-question-demanding newbies has to do with the excellent marketing that DHH and the crowd at 37signals has done for Rails–specifically the idea of scaffolding and the mind-blowing videos circa 0.13. The video demos tap into the age-old (well, okay, maybe like 40 years old) desire to abstract the actual programming into thin air, and visions of programming a fully functional shopping cart in a single day flash before people’s eyes. They bang around with scaffolding before finally realizing there is no ––do-the-work-for-me switch for rails, at which point they end up in #rubyonrails or a forum somewhere, asking the ineffable, and effing the answerers.
Amy does a great job of analyzing these folks–”help vampires,” she calls them, with a remarkable amount of restraint–but they’re only one component in a a larger system. Rails newbies are like unsuspecting mogwai–big eyes, fluffy, and utterly clueless. Somewhere along the line, they turn into gremlins–help vampires–and start demanding help, tearing up the couch, and tossing popcorn about all willy-nilly. It’s important to know how to handle a gremlin, but there’s a deeper question at hand: who the hell’s been feeding the little buggers after midnight? (For those of you who haven’t seen Gremlins, I mean “what turns a Rails newbie into a help vampire?”)
One of the first things you learn in conflict resolution is that when people repeat themselves it’s because they don’t feel heard. One of the first things you learn about usability is that when the same problem pops up often it’s because the product is flawed. And one of the last things you learn about technical support is that when the same stupid question rears its head over and over and over again it’s because the answer is probably tucked away in a wiki, sandwiched between blackjack spams, and preceeded by a Flash splash screen which says “beware of leopard.”
So what’s the solution? How do we make it easier for people to jump in with both feet into the Rails experience? How do we turn curious newcomers into tattoo-sporting diehards? How do we make everything outside of the code as beautiful as the stuff on the inside?
Over the next few days I’ll detail my ideas for making the Rails experience more welcoming and productive. I promise you now they’re good ideas–worth reading, even. I’d love to hear from you all about some of the strong and weak points you’ve experienced with the Rails community, and I’m curious to hear what you all think we should do about it.
Next up: it’s so hard to find good help these days…
2 comments »So, I switched the feeds here over to FeedBurner, mainly in hopes of getting Google to finally get that my site is not just a collection of empty RSS2 files. Yeesh.
In other news, I got hit by a car last Thursday night. I’m fine, really: missing some skin on my knee and elbow, but my rib right below my right pec hurts like hell. I don’t know if I pulled a muscle or cracked a rib, but the pain is a nuisance, not a grinding horror, so I figure I just try not to get hit by cars until it gets better. Yeah, that’s my health plan these days. Duck and cover.
In other news, the search plugin I’ve spent so much time on recently is about done. It’s cleaner than hell, does a decent job of ranking results, plays very nicely with associations, and uses only two database queries per model. It’s wonderfully extensible, rather compact, and requires that you use Rails Edge (soon to be 1.1!). I will post more details perhaps this weekend.
Until then, remember: that car does not see you and will not signal or otherwise indicate its intention to merge right over your ass.
1 comment »Well, I’m not terribly sure why, but for whatever reason, Google decided that the authoritative version of each of my posts was the content-less RSS2 comments feed:
Now, I can understand that my being number one in Google’s results for “ruby howto” may have been a fluke. That said, I find it absolutely insane that searching for “Coda Hale” doesn’t return any hits from my main website which is updated every week or so.
Whisky tango foxtrot, Google?
Obviously I’m miffed because this happened right after I got Mint, so I get to see the number of people coming to this blog dropping off until, instead of a histogram, it just has a cartoon of some sad mothballs. Anyways, I’ve removed links to the RSS2 comments feeds (sorry, world) and set up a 301 redirect from them back to the actual content.
DO YOU HEAR ME, GOOGLE? I’M RIGHT OVER HERE. WITH THE CONTENT.
I’ve even delayed releasing a few plugins because no one would notice, so to commemorate Google rediscovering this site (knock on wood), here’s a taste from an upcoming plugin:
class Person < ActiveRecord::Base
has_one :teddy_bear
has_many :robot_enemies
searchable_by :fields => [:name, :description, :teddy_bear, :robot_enemies],
:include => [:teddy_bear, :robot_enemies]
end
class PeopleController < ApplicationController
def search
@results = smart_search :for => params[:query],
:in => [Person],
:limit => 10
end
end
And I’ll say this much: it’ll even work in SQLite.
2 comments »