Re: Ruby Docs with annotations and searching
mathew <[email protected]>
| Newsgroups | gmane.comp.lang.ruby.documentation |
|---|---|
| Message-ID | <[email protected]> |
John Gabriele wrote: > On 5/18/06, mathew <[email protected]> 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