Brainstorming ideas how to improve Ruby's documentation

ruby-talk
1

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

2

I agree with what your overall aim is, which is to improve the non-reference
documentation so that new users can learn Ruby more easily. There are
efforts being made on other discussion threads for that.

However, I think as _reference_ documentation, RDoc serves its purpose quite
well. It might not be the most cutting edge design, but its more than
functional enough.

I think there would be more problems if we scrapped the reference
documentation for _just_ tutorial-style material. It doesn't have to be RDoc
which produces the reference docs, of course, but we do need to keep both
levels of information. I don't want to have to walk through an introductory
tutorial to find the precise definition of String#split(a, b) for example,
when I already know Ruby.

3

Hello,
I'm on my way to learn Ruby (with a Windows background), and I really
agree with the fact that the different online Ruby documentation I could
find REALLY didn't suit my needs and my way to learn something.
I bought several interesting books that solve my problem, but I can
confirm that the existing online Ruby doc was really not appealling for
me...

···

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

4

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

  Ruby Programming Language

[snip]

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

  The Python Tutorial — Python 3.12.1 documentation

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

Did you notice that on that ruby-lang.org link you provided there's a
menu item to the right that says "Ruby in Twenty Minutes"? It leads to a
quick introductory tutorial for basic Ruby use. I'm not sure your
comparison with Python is entirely fair, considering you're comparing an
apple (Ruby API docs) with an orange (a Python beginner tutorial).

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

From what you've said so far, I don't think your problem is with RDoc per
se; I think it's with the atrocious frameset Web interface.

···

On Fri, Aug 05, 2011 at 05:48:08PM +0900, Marc Heiler wrote:

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

5

I fail to see how an API documentation generator is related to
creating tutorials for a language.

···

On Fri, Aug 5, 2011 at 10:48 AM, Marc Heiler <shevegen@linuxmail.org> wrote:

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?

--
Phillip Gawlowski

phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw

A method of solution is perfect if we can forsee from the start,
and even prove, that following that method we shall attain our aim.
-- Leibniz

6

well, OK... forget it. my mistake. I use the forum interface and didn't
even think that it was a mailing list behind.
never understand why mailing list are used instead of forums.. whith
search/edit functions..etc. (and can't imagine how someone could
organize a mailbox with that. what if I add a mailing list incoming in
my mailbox for all of my interests... ouch..)
but forget it. back to the original post. sorry again.

···

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

7

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.

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

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:

Ruby Programming Language

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

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:

RDoc Documentation

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:

RDoc Documentation

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:

The Python Tutorial — Python 3.12.1 documentation

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

8

As a longtime [former] Java programmer, I have always found the java
documentation repository extremely well implemented. My suggestion
would be to make the ruby docs repository resemble javadoc's.

Yes, they utilize HTML frames, but that's no hindrance to me. If
anything, it helps break up the largness of the documentation. Check it
out for yourselves:

http://download.oracle.com/javase/6/docs/api/

···

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

9

I hate frames, too, but I find the non-frame Darkfish layout
in RDoc 2/3.x very usable with lynx and Vimperator (firefox).

Darkfish is even usable without JavaScript[1]. In fact, I don't think
I'd have halfway usable websites for my Ruby projects without
Darkfish.

One (important (to me)) thing I do with my RDoc + Darkfish sites is
remove the default index.html and and replace it with the HTML for
README, leading to an index column on the left.

Contrast the following two, I prefer the latter to be the default
index page:

  http://rdoc.rubyforge.org/index.html
  http://rdoc.rubyforge.org/README_txt.html

While I'm bikeshedding, I do wish RDoc didn't use icons/JS at all. The
The only useful tags in HTML to me are <a>, <title> and <pre> :slight_smile:
However, I don't think I'm representative of the Ruby community at
large.

[1] I wrote wrongdoc to strip JS from all the RDoc I upload to
    bogomips.org: wrongdoc - RDoc done wrong
    I couldn't get alignment to work right w/o icons, though...

···

Marc Heiler <shevegen@linuxmail.org> wrote:

If you do not believe me, click on it:

  RDoc Documentation

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

--
Eric Wong

10

Agree on the general point.

I think you are using the wrong reference, though.

If you want to compare to an excellent documentation implementation,
look at Perl.

Perl's killer feature is its documentation, IMO.

$ perldoc POSIX
$ perldoc LWP
$ perldoc Test::More
$ perldoc -f print
$ perldoc -f open
$ perldoc perlre
$ perldoc perllol

And so on...

(For those among you cringing at the idea of a command line, there are
web pages with this, e.g.

http://perldoc.perl.org/
http://perldoc.perl.org/POSIX.html
http://perldoc.perl.org/Test/More.html
http://perldoc.perl.org/perlre.html
http://search.cpan.org/~mschwern/Test-Simple-0.98/lib/Test/More.pm\)

I think there are two sides to this:

1. Perl's community has a tradition of NOT documenting isolated
functions, but documenting modules. I guess you could fix this by
providing better tools.

2. Perl's community appreciates Perl's documentation a lot, so module
authors do write good documentation. This needs a change in attitude.

Marcelo

···

On Fri, Aug 5, 2011 at 02:48, Marc Heiler <shevegen@linuxmail.org> wrote:

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

11

Text itself is fine, but I agreed, RDoc output is ugly and unusable

Why can't it be like this http://railsapi.com/doc/ruby-v1.9.2

···

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

12

Actually I'm very glad to see this topic, the fame of Rails is powerful
catalyst, but it can't do all the marketing for Ruby alone.

I believe it's important to constantly improve and constantly move in
the future and have the courage to drop some outdated luggage from the
past.
Especially now when there's so attractive solutions like Node.js.

But, the intention in this topic looks like a demand, I think that we
shouldn't demand something from the core team, but instead try to create
alternatives by themselves (not only docs, all aspects of ruby, and I
very glad to see emergence of things like JRuby and Rubinius ).

P.S.
After writing that I realized that this time I demand to do something
from You. So, I decided that my demand is also wrong and at first I
should do something by myself.

So, I build up the documentation site with alternative style (using
sdoc) for ruby - http://ruby-doc.info

sources https://github.com/alexeypetrushin/ruby-doc

···

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

13

What are you talking about? Ruby has a nice docs, railsapi.com for example.

···

2011/8/5 Fred L. <f.linard@fdtec.net>

Hello,
I'm on my way to learn Ruby (with a Windows background), and I really
agree with the fact that the different online Ruby documentation I could
find REALLY didn't suit my needs and my way to learn something.
I bought several interesting books that solve my problem, but I can
confirm that the existing online Ruby doc was really not appealling for
me...

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

14

I think RDoc is mostly fine for what it does, but people tend to misuse
it (or, more precisely, *barely* use it, resulting in *barely* having
documentation). As a result, a lot of the time the so-called
documentation is basically just an empty space on a page where
documentation should be. The Web interface with the ugly frames is an
utterly atrocious interface, too; I agree with that.

···

On Fri, Aug 05, 2011 at 06:07:29PM +0900, Adam Prescott wrote:

I agree with what your overall aim is, which is to improve the non-reference
documentation so that new users can learn Ruby more easily. There are
efforts being made on other discussion threads for that.

However, I think as _reference_ documentation, RDoc serves its purpose quite
well. It might not be the most cutting edge design, but its more than
functional enough.

I think there would be more problems if we scrapped the reference
documentation for _just_ tutorial-style material. It doesn't have to be RDoc
which produces the reference docs, of course, but we do need to keep both
levels of information. I don't want to have to walk through an introductory
tutorial to find the precise definition of String#split(a, b) for example,
when I already know Ruby.

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

15

I think you can't really rag on RDoc for not producing tutorials. That
would be like me getting mad at my fridge over the quality of the toast it
produced - wrong tool for the job.

As for the format, there are certainly improvements to be made. RDoc is on
GitHub too, and the project already has a templating system built into it.
(BTW, I just checked, and sendmeapullrequestforthat.com is still available
in case anyone wants it.)

···

On Fri, Aug 5, 2011 at 11:52 AM, Chad Perrin <code@apotheon.net> wrote:

On Fri, Aug 05, 2011 at 05:48:08PM +0900, Marc Heiler wrote:
>
> Let's consider a new user again. He visits at:
>
> Ruby Programming Language

[snip]

>
> Please, I love ruby and matz is a genius, but contrast this to:
>
> The Python Tutorial — Python 3.12.1 documentation
>
> That's right. The Python homepage tries to TEACH people HOW TO USE
> PYTHON.

Did you notice that on that ruby-lang.org link you provided there's a
menu item to the right that says "Ruby in Twenty Minutes"? It leads to a
quick introductory tutorial for basic Ruby use. I'm not sure your
comparison with Python is entirely fair, considering you're comparing an
apple (Ruby API docs) with an orange (a Python beginner tutorial).

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

From what you've said so far, I don't think your problem is with RDoc per
se; I think it's with the atrocious frameset Web interface.

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

16

You must not have a very good email client. :slight_smile:

···

On Fri, Aug 5, 2011 at 11:54 AM, Fred L. wrote:

never understand why mailing list are used instead of forums.. whith
search/edit functions..etc. (and can't imagine how someone could
organize a mailbox with that. what if I add a mailing list incoming in
my mailbox for all of my interests... ouch..)

17

They are a usability and accessibility nightmare. There's a reason the
W3C recommends *against* using frames (in fact, HMTL5 was supposed to
remove frames altogether).

···

On Fri, Aug 5, 2011 at 7:36 PM, Andy Davis <ananonana@gmail.com> wrote:

Yes, they utilize HTML frames, but that's no hindrance to me. If
anything, it helps break up the largness of the documentation.

--
Phillip Gawlowski

phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw

A method of solution is perfect if we can forsee from the start,
and even prove, that following that method we shall attain our aim.
-- Leibniz

18

While I'm bikeshedding, I do wish RDoc didn't use icons/JS at all. The
The only useful tags in HTML to me are <a>, <title> and <pre> :slight_smile:

The <hx> class of tags is useful too (semantic markup!), as is the
<table> for tabular data.

However, I don't think I'm representative of the Ruby community at
large.

Nope, I prefer a lack of JS, frames, and nonsense like that, too.

···

On Fri, Aug 5, 2011 at 10:32 PM, Eric Wong <normalperson@yhbt.net> wrote:

--
Phillip Gawlowski

phgaw.posterous.com | twitter.com/phgaw | gplus.to/phgaw

A method of solution is perfect if we can forsee from the start,
and even prove, that following that method we shall attain our aim.
-- Leibniz

19

ri String
ri String.split
etc

···

On Aug 5, 2011, at 13:42 , Marcelo wrote:

On Fri, Aug 5, 2011 at 02:48, Marc Heiler <shevegen@linuxmail.org> wrote:

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

Agree on the general point.

I think you are using the wrong reference, though.

If you want to compare to an excellent documentation implementation,
look at Perl.

Perl's killer feature is its documentation, IMO.

$ perldoc POSIX
$ perldoc LWP
$ perldoc Test::More
$ perldoc -f print
$ perldoc -f open
$ perldoc perlre
$ perldoc perllol

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?

I fail to see how an API documentation generator is related to
creating tutorials for a language.

Thank you. I was becoming concerned with how many people seem to think they
are the same thing.

well, OK... forget it. my mistake. I use the forum interface and didn't
even think that it was a mailing list behind.
never understand why mailing list are used instead of forums.. whith
search/edit functions..etc. (and can't imagine how someone could
organize a mailbox with that. what if I add a mailing list incoming in
my mailbox for all of my interests... ouch..)
but forget it. back to the original post. sorry again.

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

I do that. I have gmail automatically tag them and remove them from my
inbox. Then I just go check the tag every now and then, and see what's new.

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.

I agree, I prefer the ruby-doc style docs (though I've never figured out why
they list the files). And I also agree that the Pickaxe is probably the best
Ruby book there is. I think they could do with removing the API that takes
up a few hundred pages, but man, there is some _really_ great stuff in
there. Not just API things, but intermediate things like how to structure
your programs, and even extremely advanced things like how to wrap a C
library with Ruby. I wish I had read it long before I did (I was put off by
it's 1000 pages).

···

On Fri, Aug 5, 2011 at 5:49 AM, Phillip Gawlowski <cmdjackryan@gmail.com> wrote:

On Fri, Aug 5, 2011 at 10:48 AM, Marc Heiler <shevegen@linuxmail.org> > wrote:

On Fri, Aug 5, 2011 at 5:54 AM, Fred L. <f.linard@fdtec.net> wrote:
On Fri, Aug 5, 2011 at 7:47 AM, Keith Bennett <keithrbennett@gmail.com>wrote: