I.NFECTIO.US

• 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.

By open source book, I mean a separately maintained API reference 
maintained in book form, organized into logical chapters and topics
with full API coverage and plenty of examples. Take the API docs 
for AR associations. ActiveRecord and its associations are documented
across many files making it difficult to provide full and complete
examples of its many use cases inline. Having a dedicated chapter to
cover each association with full example coverage and feedback 
capability would be better than the inline docs. The inline docs 
should provide full API coverage, but leave the examples out. This
other "officially" maintained documentation would contain the 
example coverage and many use cases as well as user feedback.

Yes this is extra work, but I think you could find plenty of 
volunteers, including myself, to make up an official rails-doc 
team with full commit rights to the documentation in rails trunk.