From: Keith Bennett <keithrbennett@...>
Date: 2011-08-05T21:47:50+09:00
Subject: Re: Brainstorming ideas how to improve Ruby's documentation

--Apple-Mail-2--766200394
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii

Marc and All -

Let's not forget that the people who created all the things being =
complained about most likely did it on their own time, as a gift to =
their technical community.

Let's not forget to be grateful for their efforts, and the benefit that =
it has given us for many years. =20

I don't understand what you mean when you say "And totally unusable as =
well by the way." -- how is it unusable?  And how is the Pickaxe book =
ready for retirement?  It's an outstanding reference, and I'm often =
consulting it.

Ruby is not a commercial product.  If something is suboptimal, we =
ourselves are responsible.  It's constructive to suggest improvements, =
but I wish you would do it in a tone that acknowledges and appreciates =
the efforts and accomplishments of those whose work you want to improve. =
 Are you willing to invest the mega-hours that they did?

- Keith

---
Keith R. Bennett
Blogs: http://krbtech.wordpress.com, http://keithrbennett.wordpress.com



On Aug 5, 2011, at 4:48 AM, Marc Heiler wrote:

> The title is misleading...
>=20
> Sure, I want you to brainstorm ideas, but this is also a rant.
>=20
> We need NEW ideas and for this to happen some OLD ideas must die.
>=20
> Ok, those who know me know that I think Ruby's documentation has a lot
> of room for improvement, to put it mildly.
>=20
> One thing I would like to see is RDoc's death.
>=20
> I really want to see it die.
>=20
> When it has died, there is plenty of room for alternatives.
>=20
> Yard may be an improvement but it simply is not enough.
>=20
> 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.
>=20
> Let's consider a new user again. He visits at:
>=20
>  http://www.ruby-lang.org/en/
>=20
> Ok, so he visits that page and goes to documentation which leads him =
to:
>=20
>  http://www.ruby-lang.org/en/documentation/
>=20
> He then goes down to "Reference Documentation" (and by the way, why
> isn't there an extra link to the CORE API directly please?)
>=20
> Now he clicks on this:
>=20
>  "Ruby Core Reference"
>=20
> And this brings him to a page:
>=20
>  http://www.ruby-doc.org/core/
>=20
> Now the new users says this to himself:
>=20
> "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 ..."
>=20
> And he is right. This page is not usable.
>=20
> The bytes that are transmitted are a waste of bandwidth.
>=20
> If you do not believe me, click on it:
>=20
>  http://www.ruby-doc.org/core/
>=20
> There you have it. HTML Frames in all their ugly glory.
>=20
> And totally unusable as well by the way.
>=20
> Please, I love ruby and matz is a genius, but contrast this to:
>=20
>  http://docs.python.org/tutorial/index.html
>=20
> That's right. The Python homepage tries to TEACH people HOW TO USE
> PYTHON.
>=20
> Can't ruby learn from python here?
>=20
> Ruby has the better design, but python kicks its butt because it has =
the
> MUCH MUCH better documentation.
>=20
> Please, kill rdoc at once even if no alternative exists. No =
alternative
> is still better than the crap that is called Rdoc.
>=20
> 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?
>=20
> Some valiant heroes tries to improve the documentation, but honestly.
>=20
> 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.
>=20
> The Pickaxe guys did a GREAT job but it is time to retire the Pickaxe.
> Why? Not because I hate the guys.
>=20
> BUT BECAUSE I THINK RUBY'S DOCUMENTATION IS SO HORRIBLE THAT A GIANT
> LEAP MUST BE TAKEN NOW.
>=20
> 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.
>=20
> Do we really want to have this?
>=20
> --=20
> Posted via http://www.ruby-forum.com/.
>=20


--Apple-Mail-2--766200394--