Hi,
it is quite difficult to define what is lacking in documentation, until
the time comes when one is trying to get something to work and cant
figure out how to do it. Having now been learning Rails (and Ruby) for
several months, and not coming from a strong web programming
background, I will try to say what I have found most difficult.
The whole subject of Rails, covers an enormous breadth, and to the
newcomer, it is difficult to know how to drill into it. The various
tutorials around the web cover the basics of creating a simple app, but
when it comes to wanting to do specific things it is difficult to know
how to get at the information you want. It is almost always out there
somewhere, but it involves picking up bits and pieces from the forums,
tutorials, manual, wiki and api.
I think that the problems I have faced have been 2 sided. On the one
front, when I find a method that appears to do what I want
(particularly with some of the helpers), it is not always clear how to
use it. The explanation is just that bit lacking. It is fine when you
know what it does, but getting there in the first place takes too long.
Often just a few more words would clarify how they work, particularly
with respect to the argument lists.
On the other front, is the difficult problem of "I know there is a
method that does just what I want, but I cant remember what it is
called - eg. was it pluralise, capitalise, humanise? just what was
that method that changes to this_case to ThisCase. Some of these are
difficult to put into meaningful phrases so even google does not always
help. Perhaps it's not actually in Rails, but in Ruby I should be
looking.
There are lots of cheat sheets around, but invariably what I am looking
for is not in them.
There is no doubt the the Agile Rails book is incredibly useful, but
sometimes even using that it has taken ages to find the specific thing
I am looking for.
I really dont know if any of this helps, but perhaps it sumarises as:
1. Improved explanations
2. more simple/short examples
3. consolidation of all of the resources
4. Indexing/cross referencing/searchability
The php manual is pretty good it is quite well structured and indexed,
functions/methods are described and the comments added by the community
serve to provide examples and clarifications.
I appreciate that php is a language and Rails is a framework and that
in itself is another problem.
BTW, wasn't there an initiative a while ago to take on a professional
full time documentation person. If someone has been looking at this
now for quite a few weeks, perhaps some ideas and approaches may be
developing. One danger I can see is for various different versions of
documentation to appear on different sites. It is already difficult
enough to remember where I saw a particular bit of information, but if
several sites pop up trying to document Rails in different ways, it
could become a greater problem.
Tonypm
It's possible that there are things an
online version could do that I've never thought of, and that I'd find
useful if I saw them. I've always found api.rubyonrails.org pretty
complete and easily navigable.