This post originated from an RSS feed registered with Ruby Buzz by rodney ramdas. Original Post: About that Rails API Feed Title: pinupgeek.com Feed URL: http://feeds.feedburner.com/pinupgeek Feed Description: A personal take on Ruby and Rails Latest Ruby Buzz Posts Latest Ruby Buzz Posts by rodney ramdas Latest Posts From pinupgeek.com

Dear Reader, i’m in bed, I have a nasty cold and I’m feverish. Yes, please do feel sorry for me. All my sinuses are clogged, I’m a really sad person at the moment. However being in bed with macbook does give one an opportunity to think. So while antibodies are being devised to fight the battle for me I can finally give my blog some much needed loving. Here’s something I’ve been moaning about.

At the Caboo.se work is progressing rapidly on Rdoc, the collaborative Rails documentation project. In the meantime I’ve been evaluating my own use of the currently available documentation. I came up with a list of sites and tools I used daily if not regularly when doing Rails development. Looking at the list you might get inspired to pitch in some ideas on how to make the Rails documentation better. My own personal view on the docs is that they’re not really bad or extremely out of sync with the code base but rather that the API docs are not very accessible.

The current rdoc representation of html within frames, lack of a good search option except for your browsers control-f makes it awkward to use. There a some sites that remedy that problem but I think there’s a lot of room for improvement there. So while we at the Caboose are focussing on improving the actual API documentation I think a separate project might be started somewhere to see if we can find a better presentation of the documentation. We can start by looking at how other API have been documented. I’m interested in learning from you what constitutes “good documentation”. But first the list I promised:

1. The Official API

Slightly awkward to use this is a trusty work horse. Stable branche only. So to me of limited use since the projects I work on are Edge only at the moment. But if you’re less adventurous not a bad place to look.

2. The Unofficial cracked open Edge API

This is the API provided by Caboo.se and the one I use daily. It’s the rdoc from Edge with all the :nodoc directives removed, hence “cracked open”. If you need to look under the hood or if you’re paranoid and dislike secrecy this is the API for you.

3. Rails Help

This is a fantastic place to find API answers very quickly in a nicely presented way. I love this site. I have no clue who made it. It has a nifty live search going on which makes it even more adorable. To me this site represents how the Rails API should look like from an esthetic point of view. Simple, clean, well designed, accesible.

4.The Annotated Rails API

Don’t bother clicking on that link. I’m not sure what happened to this project. It seemed to be going quite strong when it was launched. Basically here users could annotate the API by leaving comments in the style some know from php.net and mysql.com I don’t think it really took off and I can’t quite understand why. Are Rails users not that keen on sharing information ?

Those are the sites that I know of that deal with the API in one way or the other. What follows are sites that have a more tutorial style approach. Still documentation but in a different form:

5. Rails Manuals

Here you’ll find online books on Capistrano, an upgrade guide, how to start TDD with Rails and more. Very well done. I’d like to see these expanded. The tool used there is Hieraki, a collaborative bookwriting app written in Rails and by the looks of it, it works quite well. It’s not hard to imagine a “Programming Rails” manual there or a “Beginners Guide to Rails”. All it takes is a couple of writers with some time on their hands.

6. The Rails Wiki

There’s a lot of info here. I’ve yet to find something that was wildly inaccurate.

7. Peepcode

I lack superlatives for Peepcode. This is the only non-free “documentation project” on this list but it definitely belongs here. Peepcode gives you a lot of value for money with screencasts, cheatsheets and working code for you to jump start your understanding of Rails. Geoffrey deserves an Oscar for this.

8. Last but not least: Railsweenie

Rick Olson’s Railsweenie has been the place to turn to for hardcore Rails knowhow for quite a while. He recently revamped the interface and moved it to Beast, a more forum-like user experience. And I think that was a good decision.There’s a lot of activity on Railsweenie and it’s rapidly becoming an alternative for the noisy #rubyonrails irc channel and other lesser forum attemps. Like I said Rick just moved it over to the new interface so things can be shaky, but that shouln’t hold you back.

So what great sites/ideas am I missing here ? I’ve been trying to find inspiration for how the Rails doc could look like. I really like the way Apple has documented Cocoa. It consists of a series of Guides, each focussing on a particular area. It searchable and gives you both html and pdf as reading options. The interface is consistent and clean, no clutter. You can give feedback , but no annotation options. Next to Guides, they have Reference, i.e. API documents. Again very readable. Have a look for instance at NSURL. Great use of tooltips too. I’m interested in learning what other reference docs you’ve come across that you really liked or hated (and why).