From: Michal Suchanek <hramrach@...>
Date: 2007-12-18T21:35:42+09:00
Subject: Re: Language Popularity - PHP vs Ruby?

On 18/12/2007, Chris Cummer <chris@postal-code.com> wrote:
> 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.

No, php docs cover like 99.9% of the core functionality + standard
libraries. That cannot be said for Ruby. Some of the standard
libraries do not have any documentation at all, some of the details of
core functionality are only explained in the pickaxe which is not
integrated with rdoc.

However, the task of documenting PHP is much easier than that of
documenting Ruby. PHP only covers web, db, and supporting system
tasks. The situation for something like php-gtk might be quite
different. I do not know of any TUI library for PHP,and it's certainly
not in the core. Also there is nothing like yaml,
marshal,singleton,delegator,...

iirc they only reference the regexp library docs instead of explaining
the two regex flavours they use in detail. That's the joy of relying
of somebody else's stuff ;-)

Note that if it weren't for user contributed examples some of the core
function details would be far from clear. So the user contributed
comments are very valuable part of PHP documentation.


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

You can more or less do that for rdoc because of the frames. Very
clunky, though.

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

Yes, and it would be only fair to compare PHP documentation with Rails
documentation, the scope is about the same.

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

Creating what PHP has would require replacing the static rdoc frames
with dynamically generated scripted index-menu. It can be cached but
the scripts have to be in place to generate the menu for new queries
or when the docs get updated. It's not too hard but somebody has to
write the scripts ;-)
Tho comments would require even more complex site with database and whatnot.

Thanks

Michal