--IbA9xpzOQlG26JSn
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On 25/09/06 Austin Ziegler said:

> There aren't. I think you're missing out on several factors and reacting 
> badly.
> 
> 1.  ruby-doc.org is not maintained by the core Ruby website folks.
> James Britt, the maintainer of ruby-doc.org, does so on his time. The
> core Ruby website is and always has been ruby-lang.org and can be
> considered more up-to-date than most other websites about Ruby with
> respect to releases. ruby-doc.org is good, but it is an independent
> but related project, not part of the main website.
> 
> 2. There was only one *release* of Ruby 1.8.4. There wasn't even a
> security patch (1.8.4.z) released. After release, there are dated
> stable snapshots available. It is possible to get a Ruby 1.8.5 that
> has further fixes available with recent changes as of right now. But
> if you download Ruby 1.8.5, you're getting ONLY what was released
> there.

Core site or not,

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

points to ruby-doc as it's standard and core library references. They
shouldn't do that if they're not vouching for their authenticity.

I downloaded the 1.8.4 tarball long after it was considered the stable
release, AFAIK. If there was only one release, then I got it. The links to the
1.8.4 docs should lead one to docs on 1.8.4, yes?

If one goes to http://www.python.org/doc/, you get docs for the latest release
that are up-to-date, and maintained by the project itself. More importantly,
as you're likely not using the latest version in production, you can go to
http://www.python.org/doc/versions/ and get old versions for your version. You
can also separately browse the in-development versions. It's always clear what
you are looking at.

Now, if it's very difficult to keep these up-to-date, then there are issues
within the Ruby development community to solve, since the tools are there.
Otherwise, it would be very nice to see the Ruby development community
maintain a model like I've referenced here. I constantly find it difficult to
get the information that I need to effectively use the language, and I don't
think that I'm alone.

It's worth the battle so far, as I am _loving_ the language. Still, the
pickaxe book as an API reference is incomplete. ruby-doc says it's showing
1.8.4 but it's apparently not. There's a free pickaxe book online from the 1.6
stream. I get inconsistent results on the code in the tarball from the ri
tool. This is an exercise in frustration. I have precious little free coding
time for my own projects, and I don't want to spend it crawling through Ruby
source trying to decipher the API. It's very difficult to justify my using it
internally at work when I'm surrounded by Java people who have far better
documentation than me.

How can I help this situation? I guess I'll start by talking to the owners of
ruby-doc, and seeing if I can help.

Mike
-- 
Michael P. Soulier <msoulier / digitaltorque.ca>
"Any intelligent fool can make things bigger and more complex... It
takes a touch of genius - and a lot of courage to move in the opposite
direction." --Albert Einstein

--IbA9xpzOQlG26JSn
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)

iD8DBQFFF9nSKGqCc1vIvggRAoqyAJ4g27yx8rBJTSZJowK4or5Hp8cykQCfcxlk
V6s5hrKkfWU82a823iW62kU`i2
-----END PGP SIGNATURE-----

--IbA9xpzOQlG26JSn--