Panasonic Youth

All Ruby and Rails APIs suck (but its getting better)

All the online APIs for Ruby and Rails suck. Thats been a given for a long time. Note that I’m not talking about the actual Rails Rdoc content itself - the doc project patches continue to roll in, and the HackFest also saw many doc patches merge in. The Ruby Rdoc content, well, a lot of is still pretty spotty.

By online APIs, I’m referring to the web front ends to the rdoc. The default Rails api site (https://api.rubyonrails.org/) is clumsy, has no search, uses frames, and has many methods hidden since they are #nodoc’ed. Its probably out of date, too, but there really isn’t a way to tell what Rails version its actually from. The caboose docs at least removes the #nodoc, but the search box is pretty much broken, and the interface is still just as bad. Rails Manual adds annotation support (which is pretty much unused), has a little bit better search, but is still out of date. Its also getting clobbered by spammers now, so I guess Rannotate should integrate a captcha (natch). Ruby.search combines a few api sources and has a nice little ajaxy search, except that it still doesn’t work right (try searching for “activerecord” or “base”). Also, there is no Ruby 1.8 api, just the PickAxe, which is Ruby 1.6. Finally, there used to be www.railshelp.com and rails.outertrack.com, but both are dead now. To paraphrase the Geto Boys, pour some brew throughout the crew to remember the homies that left us.

“Are you just going to criticize, Rob? PDI!” Fine. I’m going to offer my ten point plan for the Totally Radical Rails and Ruby Documentation Engine (.com):

  1. Better content. The doc patches should keep coming in, whether its from the doc project or the rest of the community.
  2. A better UI. Rails brain is a good first step for this, but there is still lots of room for improvement. The search results should be cached in javascript for speed. Keyboard shortcuts should be expanded for things like page up, page down, switching to different methods in the main pane, and shift-tabbing between the options on the left. Something like "my favorites" could save the top 10 classes I always go to, for easy access to the APIs I use most.
  3. Annotations. Php.net is often pointed to as the holy grail for this, but I gotta tell ya - the user comments there are a mess. There is a ton of good content, but also a lot of crap from developers who don't know what they are talking about. Its also just plain difficult to follow the conversation in any of the more active pages. So take the php.net model of having one official site where all annotations go, add a better UI and some sort of peer review system like reddits, and now you're talking. See also the django book for some of this.
  4. A clear statement of what version is covered, along with links to older version. See django. again. If you haven't look at the django docs you really should.
  5. Links on each method, class and file to search for "foo" on the Rails list, Ruby blogs, snippets sites, delicious, etc. Embrace the rest of the web and the many APIs and discussion elsewhere.
  6. Integrate core Ruby and the stdlib. If you aren't learning the core libraries, you aren't taking full advantage of the platform. The core Ruby docs are just about as bad as the core Rails docs, and it makes sense to have an option to search both or either alone.
  7. An active resource API for painless interoperability.
  8. A downloadable, offline version. Not only for offline work, but the speed of offline browsing can't be beat.
  9. A liberal open source license so the community can rally around it and the core team can support it. If there are five competing doc projects, none of them will get the discussion (in annotations) or then community to make things happen.
  10. CSS from top designers - if it looks cool and has sexy syntax coloring, it will be more fun to use.

So. Lets have a hack night at Rails Conf, and make it happen. I get to Portland on Monday, so I’ll have some free time. Rock n roll McDonalds?