John Gabriele wrote:
On 5/18/06, mathew <meta@xxxxxxxxx> wrote:
Who ever takes the time to read
through ruby-talk, look for things that should be incorporated in
documentation, and update the Rdoc? Me and, what, 2 or 3 other people?
Given that, how likely is it that the nuggets buried in threads on this
proposed site will ever make it into organized, structured
documentation, assuming nuggets appear in the first place?
Doing what you describe is gruelling work. I would guess it generally
involves poring over a thread that you may not be intently interested
in, boiling it down, and then finding the .rb source file it belongs
in, editing it into something good, and then handling the commit
yourself. You're pulling the whole load! Asking people to do all that
is a tough proposition.
Right, and this proposed web site has exactly the same problem.
The rub is that your procedure may be the hard way. An easier way
might be with Conor's idea. It's a lot easier to hop on over to an
RA-Ruby site, log in, click an edit button, and write something down
quickly just after you've learned about it on ruby-talk (or from
reading a book, or whatever). After a few folks do this, you will
likely end up with something good that might be able to go into the
official docs. Now all it takes is for someone with commit access (or
the moxie to post a patch to ruby-code I suppose) to do a fairly
simple procedure to get these docs in.
Except the "fairly simple procedure" is exactly the one you just said
was "a tough proposition".
Instead of just writing up some docs and then going in to ruby-core
cold with hat in-hand, wouldn't it be nicer to have your docs online
for a little while first, with others adding comments/docs below them,
possibly making corrections/additions/suggestions creating a more
complete picture?
Maybe. Personally I feel it already takes long enough to get docs
written and committed, and I use ruby-talk to pick up suggestions.
mathew
|
