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
···
On 6/16/06, Tom Allison <tallison@tacocat.net> wrote:
--
Austin Ziegler * halostatue@gmail.com * http://www.halostatue.ca/
* austin@halostatue.ca * You are in a maze of twisty little passages, all alike. // halo • statue
* austin@zieglers.ca
