Brainstorming ideas how to improve Ruby's documentation

Ruby
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:

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

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…

4

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

2011/8/5 Fred L. [email protected]

5

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

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.

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.

6

On Fri, Aug 05, 2011 at 05:48:08PM +0900, Marc H. 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.11.4 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.

7

Alexander Litvinovsky wrote in post #1015099:

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

2011/8/5 Fred L. <;;;;;;;;;;;;>

Was it necessary to post a reply with my mail address in it …???

can someone please edit it…?

8

On Fri, Aug 05, 2011 at 06:56:16PM +0900, Chris K. wrote:

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.

I think you replied to the wrong guy. I didn’t rag on RDoc for not
producing tutorials. I think Marc H. might feel like the presence
of
RDoc makes people think they don’t need to write tutorials, though, thus
providing a social impediment to the development of good tutorials.

By the way – is there any chance you could avoid TOFU 1 posting in
the
future?

9

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

10

On Fri, Aug 5, 2011 at 11:07 AM, Fred L. [email protected] wrote:

Was it necessary to post a reply with my mail address in it …???

can someone please edit it…?

Ruby Forum is an interface to the ruby-talk mailing list. Your email
address
is public whenever you post:
http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/386240

The archives are at
http://blade.nagaokaut.ac.jp/ruby/ruby-talk/index.shtml

11

If you are talking about Alexander Litvinovsky post where he said
“What are you talking about? Ruby has a nice docs, railsapi.com for
example.” he included the whole of your message as was sent to the
list, it was just the forum that truncated it.

Also try googling this “What are you talking about? Ruby has a nice
docs, railsapi.com for example.”, the third result is this list. If
it’s on Google then its about as public as it can get. This post will
probably be there within a few minutes of me posting it.

12

On Fri, Aug 5, 2011 at 10:48 AM, Marc H. [email protected]
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?

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

–
Phillip G.

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

13

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.

14

Adam P. wrote in post #1015112:

Ruby Forum is an interface to the ruby-talk mailing list. Your email
address is public whenever you post…

well ‘public’ for the list members… but not clearly visible online.
by including my mail address in the reply, it’s visible online here
http://www.ruby-forum.com

wher I see it, because I’m using this interface and not the mailing
list.

but by the way, why delete all my post, and just keep my mail address
included ???

15

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

16

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

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

17

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/

18

They are a usability and accessibility nightmare.

Can you elaborate? The ruby documents --RDoc and the stdlib-- are in
frames. It sounds like the document masters wouldn’t agree.

Personally speaking, I’ve yet to find any documentation as well packaged
and accessible as the javadocs. Ruby docs aren’t bad, but my preference
is the javadoc style.

There’s a reason the
W3C recommends against using frames (in fact, HMTL5 was supposed to
remove frames altogether).

What reason would that be? I tend to agree that web sites that use
frames tend to be a bit ugly and difficult to use. But this pertains to
documentation, where the divide and conquer approach is very helpful.
Frames do serve a purpose, but maybe not for you.

19

On Fri, Aug 5, 2011 at 7:36 PM, Andy D. [email protected] wrote:

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

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

–
Phillip G.

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

20

Browse to the Ruby standard library with a non-frames, text-only
browser. Screen readers don’t do a much better job of parsing frames.
And consider the linking nightmare.

Maybe I’m missing something, but the linking nightmare you mention can
easily be resolved with a script. Isn’t that their purpose – to
automate the most mundane and easily-botched of routines? Unless you’re
hand-coding the files, I don’t see why this is so difficult.

For people with eyesight problems I can understand using text-only
browsers (and certainly screen readers), but the solution need not be
one-approach only. One script can generate frames (or menus), and
another can generate text-only pages. Just because frames do not
address every problem does not mean they are invalid.

And the RDoc generated documentation is in frame form because that’s
how RDoc originally outputted docs.

That still doesn’t negate the fact that someone found frames useful at
some point.

Frames do serve a purpose, but maybe not for you.

“If all you have is a hammer, every problem looks like a nail.”

You’re stating an unwarranted extrapolation. I never said frames were
the right solution for everyone. I said that it has worked splendidly
for me in the past, and that I would recommend a similar style for Ruby
docs. Again, the solution need to be comprised of a singular approach.