Language Popularity - PHP vs Ruby?

[Michal Suchanek]

Well, one often cited credo around here is that you should learn a new
language every x month, and I think that ruby profits a lot from this
attitude. Innovation often means wandering through unknown (as in
"where no man has been before" or "foreign" territory and coming
back with new ideas.

Heh, but don't start with a natural language. x would be at least in
the range of tens then ;-)

 

[Michael Granger]

Sorry to respond to such an old thread, but I didn't see this
addressed at all.

PHP isn't as consistent or beautiful as ruby, but it hardly matters
when you have online documentation like this:

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.
The online docs aren't perfect, of course, but that's true of any
documentation for any project which is still in active development. I
personally find that the online docs cover 90% of what I need, and
between referencing the source (which is where beauty very much DOES
count) and the helpfulness of the community, the other 10% is more
than covered.

We (the ruby community) really should have excellent, up-to-date,
comprehensive online documentation. Considering its online
documentation, it is amazing that ruby is as popular as it is.

What about Ruby's online documentation do you find lacking?

Are there any projects out there attempting to create good, online
documentation for ruby?

Yes, (since sometime in 2002):

http://ruby-doc.org/stdlib/status.html

is a good place to start if you're wanting to contribute your effort
to the existing docs. And you wouldn't have voiced your criticism of
the current docs if you weren't, right?

 

[Chris Cummer]

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

 

[Michal Suchanek]

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

 

[Lloyd Linklater]

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

Why can't we get something added to the core docs where there is a hyper
link or some kind of wiki that lets users add samples and explanations?
I bet that would grow into some full fledged documentation in short
order. Perhaps, when it is somewhat mature, someone could even turn it
into a freebie download PDF.

 

[Christophe Mckeon]

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

firstly let me say, rdoc is great. parsing ruby is not an easy task and
the work that went into rdoc is tremendous, but, it seriously needs an
overhaul.

it uses constants to store templates in a non-standard format in such a
way that you cannot for instance load the same template twice in one
process w/o constant redefinition errors.

it is also quite difficult to write a template. it should all be erb, or
even better, easily pluggable modules so that haml and company can also
be used. actually, somebody already hacked this together and it is not a
big hack (http://coderepos.org/share/wiki/Resh).

it should be easy to add things like syntax highlighted example code
snippets for instance, and custom navigation schemes, plain html pages,
etc...

just me 2 cents,
_c