Brainstorming ideas how to improve Ruby's documentation

The title is misleading...

Sure, I want you to brainstorm ideas, but this is also a rant.

We need NEW ideas and for this to happen some OLD ideas must die.

Ok, those who know me know that I think Ruby's documentation has a lot
of room for improvement, to put it mildly.

One thing I would like to see is RDoc's death.

I really want to see it die.

When it has died, there is plenty of room for alternatives.

Yard may be an improvement but it simply is not enough.

Even PHP, a horrible language, has an ok-online documentation, so Ruby
really has no excuse at all to not improve its documentation by about a
magnitude of 10000.

Let's consider a new user again. He visits at:

  http://www.ruby-lang.org/en/

Ok, so he visits that page and goes to documentation which leads him to:

  http://www.ruby-lang.org/en/documentation/

He then goes down to "Reference Documentation" (and by the way, why
isn't there an extra link to the CORE API directly please?)

Now he clicks on this:

  "Ruby Core Reference"

And this brings him to a page:

  http://www.ruby-doc.org/core/

Now the new users says this to himself:

"Oh, nice. A page from the ARPAnet days... must have been from 1972
judging from its layout. What am I going to do with this hmmm ..."

And he is right. This page is not usable.

The bytes that are transmitted are a waste of bandwidth.

If you do not believe me, click on it:

  http://www.ruby-doc.org/core/

There you have it. HTML Frames in all their ugly glory.

And totally unusable as well by the way.

Please, I love ruby and matz is a genius, but contrast this to:

  http://docs.python.org/tutorial/index.html

That's right. The Python homepage tries to TEACH people HOW TO USE
PYTHON.

Can't ruby learn from python here?

Ruby has the better design, but python kicks its butt because it has the
MUCH MUCH better documentation.

Please, kill rdoc at once even if no alternative exists. No alternative
is still better than the crap that is called Rdoc.

Once Rdoc is gone, start by making a TUTORIAL for the Ruby language that
is MAINTAINED by the community. We live in the days of git and github,
why shouldn't we all be able to maintain it on our own?

Some valiant heroes tries to improve the documentation, but honestly.

Just look at the quality of the python ONLINE documentation available -
you will realize that the way how ruby works, without Rdoc dying, will
ruby never ever be able to catch up to python.

The Pickaxe guys did a GREAT job but it is time to retire the Pickaxe.
Why? Not because I hate the guys.

BUT BECAUSE I THINK RUBY'S DOCUMENTATION IS SO HORRIBLE THAT A GIANT
LEAP MUST BE TAKEN NOW.

And if this won't happen I am going to recommend people towards python's
documentation from now on. Of course I will say that they must use ruby
(because ruby is beautiful, elegant, and python is ugly compared to
ruby) but I will send them to the python documentation simply because
the quality of the documentation for python is better. Then they may ask
me why I sent them to use this documentation and I will tell them
honestly that Ruby's documentation is not worth looking at.

Do we really want to have this?

-- 
Posted via http://www.ruby-forum.com/.