Collaborative Rails API Documentation
Posted by chad June 02, 2006 @ 10:14 PM
With Rails in a constant state of evolution, it’s important for its users to help each other stay in step with what’s current. To that end, Conor Hunt has created Rannotate, a system for collaboratively annotating RDoc-generated documentation.
He’s gone a step further and posted Rannotate instances for both Rails and Ruby.
Read, post, learn, and teach. At critical mass, Conor’s service could provide a huge benefit to the community. Coupled with Kevin Clark’s Rails documentation crusade, things are looking better and better on the documentation front.
These guys deserve our appreciation and our support. Now go post some annotations!
Finally! This is fantastic. PHP owed much of its gentle learning curve to such annotatable online documentation.
Hey that’s me. Thanks Chad!
I recommend subscribing to the RSS feed of notes if you want to keep up to date with the latest postings. Link is on the front page of the sites.
FYI I know there are some issues with the Ruby docs right now. I RDoc’d everything at once so mixins appear along with the main class definitions (ie. String looks like it has a to_yaml method, when actually you need to require ‘yaml’) Next release this will be fixed.
In other good news it looks Benjamin Gorlick, who is working on a google summer of code project to improve Ruby documentation, and I will be working together. Even better things are coming…
An excellent tool! I wonder if the search for the annotations still works? I tried it some time back but it seemed the search was not including annotations in the text that it was searching?
annotation searching is coming soon.. check out my blog (linked above) for some of the upcoming features.
Any chance of making the examples official? At least for Rails? It seems like the value is diluted if people start putting up multiple copies all over the place.
Ultimately it’d be nice to see it get the official nod with a URL like http://annotated-api.rubyonrails.org/ so we could get everyone annotating the same place.
It’s very cool regardless of where it goes. I love the idea of setting it up for my own app.
check out http://jonahfox.com/ruby.search
its a streamlined way to search my 3 favorites doc sources !
Wow Rannotated documentations of Ruby and Rails kick ass! The search feature is so useful. I’m using it right now on both Ruby and Rails dynamic-docs :-).
Is there some way to get the class listing on the left column persistent? I find navigating the new docs very difficult. In the old api.rubyonrails.com the class listing is instantly accessible and easy to move around in.
I hate anonymous annotations. Usually it becomes a question and answer thread for newbies.
Someone needs to make this ajaxified.
Any chance of adding this to http://www.rubyonrails.org/docs?
Great things are happening! Guys, your are awesome!
Any chance this and railsmanual.org will merge?
It would seem important to me for the Rails community to take Rannotate and back it officially at api.rubyonrails.com, otherwise it will not gain popularity among many developers, myself included.
It would seem important to me for the Rails community to take Rannotate and back it officially at api.rubyonrails.com, otherwise it will not gain popularity among many developers, myself included.
Hey Seth,
In talks right now with Conor to make that happen.
So, hopefully soon :)
This is indeed an ongoing project that I truly believe the entire ruby community will benefit by, through sharing and contributing as well as suggesting improvements along the way. Conor and I are charting a course into deep waters in some cases to work at providing the ultimate tool for understanding ruby and rails documentations. I appreciate the support by Google in my efforts for doing so through Google’s summer of code also.
RE: Bugsy on 03 Jun 19:16: “I hate anonymous annotations. Usually it becomes a question and answer thread for newbies.”
So what is wrong with that? I find the PHP documentation my first place to look, dispite the newbie questions on it. Rails definatly needs an analog to PHP documentation.