--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=
=20
> badly.
>=20
> 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.
>=20
> 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 rele=
ase
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 w=
hat
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
--=20
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=
=6pi2
-----END PGP SIGNATURE-----

--IbA9xpzOQlG26JSn--

On 25/09/06 Austin Ziegler said:

> There aren't. I think you're missing out on several factors and reacting=
=20
> badly.
>=20
> 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.
>=20
> 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 rele=
ase
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 w=
hat
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
--=20
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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)

iD8DBQFFF9nSKGqCc1vIvggRAoqyAJ4g27yx8rBJTSZJowK4or5Hp8cykQCfcxlk
V6s5hrKkfWU82a823iW62kU=
=6pi2
-----END PGP SIGNATURE-----