On 17-Dec-07, at 3:11 PM, Michael Granger wrote:

>> http://www.php.net/manual/en/
>
> Does this mean you don't know about
>
>  http://ruby-doc.org/

> or don't consider it to be "excellent, up-to-date, comprehensive  
> online documentation"? As someone who started using Ruby when the  
> only documentation was in Japanese, I find complaints about Ruby's  
> current supposed lack of documentation (online or otherwise) to be  
> surprising



To be fair, much as I love Ruby the PHP world does stand head and  
shoulders above in terms of the quality and usability of the  
documentation (that AND clause is very important). The Ruby docs are  
likely just as _complete_ in a technical sense, but the PHP docs are  
so much easier to use and search than the Ruby docs are.

THe PHP doc's ability to have user-contributed examples at the bottom  
of them is a fantastic resource, one I've taken advantage of more  
times than I can count. That you can search the docs from any page in  
the docs is also pretty nice (really, a basic requirement for online  
docs, in my opinion).

On the Rails side of things Alex Gorbatchev has done a pretty nice job  
with Noobkit (http://www.noobkit.com/), again a resource I use quite  
frequently. That it also contains the Ruby docs is a huge boon but  
there's still much room for improvement.

I guess if I could have one wish for ruby-doc.org it would be to allow  
user-contributed comments and examples ala PHP.net. There's so much  
useful information and examples in this mailing list and on the web  
that having them centralized and context-sensitive per the relevant  
doc page would be awesome.

(My other wish would be to get rid of that three-pane top-frame  
approach and replace it with a comprehensive search field and decent  
index).