From: Austin Ziegler <halostatue@...>
Date: 2006-06-17T11:33:06+09:00
Subject: Re: Whats new/fixed in Ruby 1.9 and Ruby 2.0

On 6/16/06, Tom Allison <tallison@tacocat.net> wrote:
> Austin Ziegler wrote:
> > The Ruby web pages should primarily talk about production releases.
> > Not future releases. The folks beind Ruby aren't into vapourware the
> > way that Microsoft is.
> Lovely thread...
>
> For a minute I thought there was a point in there.  But I'm not sure.
>
> I think there is something more that can be done with general documentation of
> the current Production Ruby language.  I also realize that A) this is really
> boring and B) by the time the ink dries it is probably out of date.

You're right. And what you may not be seeing -- because it's, as you
said, Really Boring -- is that there are people who are contributing
increasing levels of documentation to Ruby where it counts: in ri.
There's a Summer of Code project that will bring enhancements to
rannotate (think php.net-style documentation for Ruby). There's a new
visual identity happening soon, and I think that we're going to see a
lot of really good stuff there, as well as increasing documentation
and relevant links to the various places where documentation can be
found (articles at Artima's Ruby Code & Style, the O'Reilly Ruby blog,
James Britt's ruby-doc.org, etc.). It's just a matter that all of this
work is being done mostly by people in their (*cough-cough*) copious
free time.

> I'm not at a point where I would consider it safe for me to start putting
> together "official" rDoc publications or modifying the files themselves but
> what/how does the Ruby documentation project get things done?  (probably another
> mailing but still valid here).

You find a piece of code that you think is under-documented and you
document it. Preferably, you tell people that you're documenting this,
and then when it's done, you provide a universal patch (diff -u) for
your changed documentation. If you're document a C file, you update
the .document file, too -- but I'm not too sure about that. ;)

> I've written over 5 lines of code, so that makes me something of an expert
> according to this thread.  However, 100 lines probably doesn't move me very far
> up the food chain.

That was exasperation, but there is a point where I'd *much* rather
work with people who ask me "hey, this seems weak -- what can I do to
help" than people who say "well, this ought to be this way." Expecting
others to do it for them. Or expecting things that just *aren't*
realistic.

> But I still need docs and I spent most of last night reading the source for dbi
> trying to figure out what methods I could call and what was returned.  Glad it's
> open code, but I did find the documentation a bit lacking.

I'd talk to the folks behind the revitalized DBI project. That's
actually *separate* from Ruby itself. I don't know your background,
but that sometimes surprises PHP people, who are used to having all of
this handed to them as part of the "language."

> What constructive suggestions can someone provide to improve this for the community?

Changes. Positive criticism. Even things like "How do I establish a
connection with Ruby DBI over Oracle with Instant Client and not set
ORACLE_HOME"? That may get someone thinking and providing an answer.
Add things to wikis if you find them. *Questions* are good.
Pronouncements that something is suboptimal ... aren't. ;)

-austin
-- 
Austin Ziegler * halostatue@gmail.com * http://www.halostatue.ca/
               * austin@halostatue.ca * http://www.halostatue.ca/feed/
               * austin@zieglers.ca