I think halting development of Rails is the last thing anyone should
want. I'll have to presume you were being facetious. There have been
many good points in this thread, but "the docs suck" was not one of
them. I get blocked on things periodically, and find it difficult to
pull out of the usual resources, but more often than not the patterns
are predictable and once I've figured it out, I get a "d'oh" moment
when I realize it was documented all along, but not in the place I
expected.
Look, Microsoft throws hundreds of thousands of dollars at
documentation and the ASP.Net documentation is nearly impossible to
use. Certainly, it's no more than a catalog of methods and
attributes. You're reduced to Google and MSDN searches if you want
any context. Or a bookshelf full of $45-75 (USD) books that try to
make sense of the overall usage of the framework.
Rails is supposed to be a snap, but like most other frameworks, there
are:
- Configuration options on the machine and if you aren't used to
setting up servers, etc. it's another learning curve
- Ruby. Ok, it's a different language. Ruby is seductively easy to
use for simple tasks, but can have nuances that are not immediately
apparent
- Rails. It's a framework. There is a set of patterns Rails
addresses. The API documentation is reasonable if not exhaustive
about how Rails addresses the problem domain it covers. There is so
much enthusiasm for Rails that the Net is full of articles and new
books are coming out with increased frequency.
Over time, the documentation is sure to improve, but Rails may not be
for everyone. If you're trying to tie a few Web pages together
programmatically, PHP may be lower hanging fruit and a more
comfortable solution. If you are going for a real Web application and
don't mind chasing a dynamic, young framework, then Rails may be the
most exciting place to put your learning skills to work.
How about starting a page on the Wiki called
"ObscureOrUndocumentedIssues" so anyone with a little extra bandwidth
can try to fill in some gaps?
My $.02
