De-listing of ruby-doc.org on ruby-lang.org?

This may have been brought up before, but as a newbie Ruby programmer,
I've just been tripped up by an error in the documentation at
ruby-doc.org.

I've only just heard that this documentation is years out of date and
well-known to be inaccurate. I had no idea that this was the case and
learned the hard and time-consuming way.

If this is case, it's going to be tripping up other (new) users,
especially as it's listed first on
http://www.ruby-lang.org/en/documentation/. Perhaps a warning to this
effect, or a complete removal of the link would be justified, together
with the promotion of rubydoc.info?

···

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

I've found the 1.9 documentation on the site to be pretty OK. I don't
think I agree that it's "years out of date."

Can you share the example that tripped you up?

If we need to get the documentation site updated, I would prefer we
email those maintainers and push them to do so instead of giving up on
that resource.

James Edward Gray II

···

On Sun, Sep 11, 2011 at 9:24 AM, Matthew -- <astrochase@gmail.com> wrote:

This may have been brought up before, but as a newbie Ruby programmer,
I've just been tripped up by an error in the documentation at
ruby-doc.org.

I've only just heard that this documentation is years out of date and
well-known to be inaccurate.

I don't think I agree that it's "years out of date."

It may not be out of date but documentation of Ruby is still a shame
compared to Python.

···

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

James Gray wrote in post #1021268:

This may have been brought up before, but as a newbie Ruby programmer,
I've just been tripped up by an error in the documentation at
ruby-doc.org.

I've only just heard that this documentation is years out of date and
well-known to be inaccurate.

I've found the 1.9 documentation on the site to be pretty OK. I don't
think I agree that it's "years out of date."

Can you share the example that tripped you up?

If we need to get the documentation site updated, I would prefer we
email those maintainers and push them to do so instead of giving up on
that resource.

James Edward Gray II

The one that just tripped me up was File.open. It isn't properly
documented that File.open overrides IO.open. I believe it was also
mentioned here: http://www.ruby-forum.com/topic/1731075#999707

It confuses me how this can be wrong, especially as I'm under the
impression it's generated straight from the source code.

I don't have enough experience to judge how accurate ruby-doc.org is.
Perhaps someone with more experience than I can comment, but if it is
plagued with problems as I've been hearing, perhaps a warning should be
placed next to the link on the main Ruby website, at least until the
problems are resolved.

···

On Sun, Sep 11, 2011 at 9:24 AM, Matthew -- <astrochase@gmail.com> > wrote:

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

What happened to the call, AFAIC it was from you (I may be wrong, excuse
in advance), for overhauling the documentation thing?

- Markus

···

On 11.09.2011 17:06, Marc Heiler wrote:

I don't think I agree that it's "years out of date."

It may not be out of date but documentation of Ruby is still a shame
compared to Python.

Yeah, Ruby's primary documentation tool just doesn't show overrides as
you suggest. That probably would be handy, but it could also be
pretty tough to accomplish with how dynamic Ruby can be.

Anyway, if we're going to consider changes like that, they probably
need to happen inside RDoc. I don't think this is really and issue
with our sites so much as our tools.

James Edward Gray II

···

On Sun, Sep 11, 2011 at 10:14 AM, Matthew -- <astrochase@gmail.com> wrote:

The one that just tripped me up was File.open. It isn't properly
documented that File.open overrides IO.open. I believe it was also
mentioned here: http://www.ruby-forum.com/topic/1731075#999707

It confuses me how this can be wrong, especially as I'm under the
impression it's generated straight from the source code.

I don't have enough experience to judge how accurate ruby-doc.org is.
Perhaps someone with more experience than I can comment, but if it is
plagued with problems as I've been hearing, perhaps a warning should be
placed next to the link on the main Ruby website, at least until the
problems are resolved.

James Gray wrote in post #1021288:

Yeah, Ruby's primary documentation tool just doesn't show overrides as
you suggest. That probably would be handy, but it could also be
pretty tough to accomplish with how dynamic Ruby can be.

How does rubydoc.info achieve it? I'm really unclear as to what's gone
wrong with ruby-doc.org if other sources of documentation (that I didn't
know about this morning) are correct. The ri tool is also correct.

Not showing overriden methods is a pretty substantial problem! That
means the documentation will be wrong and misleading end to end.

In the example I found, File.open has a completely different interface
to IO.open. That's a pretty big deal. The only reason I picked up
something was wrong was because I'd just read the pickax book and
couldn't find the matching documentation. This threw me off and I've
lost confidence in that documentation all together. The trouble is, I
made the (reasonable) presumption that the documentation wouldn't
mislead me!

If I've succumb to this, there's got to be other people that have too.
IHMO, this limitation needs to be noted so that other people don't fall
into this trap too.

···

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

While we're at it, I'll mention something annoying me to no end for
some time now: ruby-doc.org's stdlib documentation is missing for some
libs. Go to http://ruby-doc.org/stdlib/ and start clicking links on
the left - soon enough you'll find some what return a 404. For
example, Win32API, soap, readbytes, and I haven't even checked a third
of the list.

If the docs for these are actually missing, then you should show some
user-friendly messages or at least a list of methods, like
rubydoc.info does.

-- Matma Rex

While we're at it, I'll mention something annoying me to no end for
some time now: ruby-doc.org's stdlib documentation is missing for some
libs. Go to http://ruby-doc.org/stdlib/ and start clicking links on
the left - soon enough you'll find some what return a 404. For
example, Win32API, soap, readbytes, and I haven't even checked a third
of the list.

If the docs for these are actually missing, then you should show some
user-friendly messages or at least a list of methods, like
rubydoc.info does.

Towards the end of last month I uploaded some updated documentation to a free Heroku instance:

http://furious-waterfall-55.heroku.com/

Note: this is a free Heroku instance so it will be pretty flakey. However all the files served are static so it won't be too bad hopefully.

When contacting the ruby-doc.org maintainer about having it hosted for the time being, he stated that there were going to be updates at some point. He also stated that there are issues with the way that RDoc does some of the processing of class hierarchy, so a custom tool is used. I've requested more information but haven't heard anything back yet. At any rate, the URL above uses an updated rdoc with the darkfish template. On a side note I'm trying to put together a Ruby Language Guide. In essence I'd like to make it something more organized. The problem with the current state of documentation from a reference perspective is that it lacks an organized structure. Take for example the Array class. Arrays have methods for obtaining values, modifying values, and iterating over values. This sort of categorization is simply too difficult to automate given the current state of things, and would require linking to some kind of external metadata.

Also the inline documentation samples are very concise (part of which is to not create walls of comments in the code) and are often written in a "here's the input and here's the output" style. There are some cases to where showing usage more tailed towards real world use requires much more detailed code.

Regards,
Chris White
Twitter: http://www.twitter.com/cwgem