Mr eel
Just a Small Gripe
What with the Agile Development with Ruby on Rails book and the excellent Pickaxe book, Rails developers are a pretty pampered bunch considering the age of the framework — only about a year.
In addition we also get the Rails Wiki and the API reference. Most of the time, if you have a problem, you can find the answer in one of these sources.
But I do have one complaint, hence the title of this post. Unfortunately the API documentation for app developers is lacking. The current API documentation seems to be aimed mainly at the team maintaining Rails. It’s a bugger because good documentation of the methods is critical for someone learning rails. I’m finding this is especially the case when dealing with ActionView.
For example, lets look at the datetime_select. This method accepts a reference to an object and one of it’s attributes — which should be datetime. It also accepts a hash of options which let you do things like omit the minute select. Unfortunately there is no documentation for the various options it accepts.
I wonder, is the plan to make the API documentation more complete or do we need something aimed more directly at app developers?
I might be going off a bit half-cocked here, but I really am a bit lost and a bit frustrated with the documentation at the moment. Are there any other sources I can look into? Should I start weeping?
Comments
Mori on August 12, 2005
You are not alone. I just had the same issue figuring out ’stylesheet_link_tag’. Even when I found the actual source code, I still needed to tunnel down to CSS to make sense of it. The Rails book uses the call frequently but never documents it. And stuff like ‘update_without_callbacks’ is even harder.
I’m a Microsoft refuge, and I’ve long been peeved with their documentation. But at least they didn’t just assume that you’d just go to the (unavailable) source code and figure it out for yourself. I want my hand held.
Mr eel on August 13, 2005
I wonder if we actually need to start a project for something like this?
I’m also often struck by how alot of the more intermediate stuff is missing from the Wiki. Perhaps the project could also encapsulate more detailed how-tos or recipies?