This post originated from an RSS feed registered with Ruby Buzz
by Bob Silva.
Original Post: Rails Documentation
Feed Title: Rails Video Tutorials
Feed URL: http://www.railtie.net/xml/rss/feed.xml
Feed Description: A growing collection of screencasts that show you how to use the many facets of the wonderful world of rails.
Improving the Rails documentation has been an ongoing discussion for awhile now. Over $15,000 has been raised by the community to improve them but nothing has come from that yet. I'm going to outline some of my thoughts about it here. These are just random thoughts and do not provide complete solutions. NOTE: This is not a rant against court3nay or the Rails Documentation Project. It's only my opinion on how it could have been handled differently.
Not to take anything away from court3nay but the timing of the Rails Documentation Project was off for several reasons. First, you should have a game plan before you ask for the money. It's been many months now since everyone donated and nothing has been done with the money. This leads to other problems, mainly it breaks the trust of the community. The next time something worthy comes along, likely contributors will be a little more cautious before they hit that donate button.
With everyone waiting to see what comes from the Rails Documentation Project, the number of patches for documentation to core has dropped.
Has anyone answered exactly what is wrong with the existing documentation? I'll outline a few things I see:
Easily gets out of date, need to place documentation on the same level as tests when accepting or rejecting patches.
The API docs on rubyonrails.org need a version selector. People using older versions of Rails (for whatever reason), should be able to access the appropriate docs for their version. This problem will be even more evident once Rails starts shipping with OS X and other Linux distros. The public website should support this, not a message explaining how to generate local documentation for your Rails version.
No style guide. You have to refer to existing documentation to determine the style to use. Could be improved with a style guide.
Are they docs or an API reference? Currently, its a combination of both and both are lacking. I think the examples need to be expanded (and possibly even follow a common theme, more on this later) and the API's more complete. When rewriting the docs for some of the ActionView Helpers, I found a quite a few options that weren't documented.
Core should have a dedicated person(s) to handle documentation issues. Making sure patches are properly documented (or willing to do it themselves) and reviewing/committing documentation patches. This person should also create the style guide or written standard for documentation.
I see two different audiences for documentation. The new users who really need a tutorial like approach and the more experienced who really need an accurate API reference. I'm not sure the inline documentation in Rails can serve both audiences, but it can come closer than it does currently. I think it would be great if Rails shipped with a default example application that all the documentation examples pulled from and referenced back to. This maintains a common theme throughout and acts as an excellent teaching tool.
So what should be done with the $15,000? Pay an author (a good one preferably) to write an open source book on Rails. This book should be completed by the author and then maintained by the community to stay current with Rails development. This is the best way I can see to spend the money.
Previous Topic
