Re: Ruby Docs with annotations and searching

On 5/20/06, mathew <[email protected]> wrote:
> John Gabriele wrote:
> > On 5/18/06, mathew <[email protected]> wrote:
> >> John Gabriele wrote:
> >> > [snip]
> >> >
> >> > 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.
> >
> > I'd agree if it were just one person adding the comments and then
> > doing the commit. But I think it's a reasonable guess that you might
> > have comments from a number of people making up the final committed
> > docs in the end.
> >
>
> But that's not where the bottleneck is. There's already tons of comment
> out there, the problem is finding people willing to turn it into
> checked-in documentation.

Hm. Well, then a worthy goal of the RAnnotate site may be: make it as
easy as possible for a committer to come along and turn multiple
select comments into something they can commit -- in as few simple
steps as possible.

It might work like this: the committer already has a source tree
checked-out, and they've got the file(s) in question open in their
favorite editor in front of them. RAnnotate might provide link on the
comments page (one per comment) to pop up a window containing raw RDoc
source of that comment.

What would probably be necessary is a way for commentors to edit their
comments. That way, someone who originally posts a good doc comment
and asks "what do you think?", can later tweak and update it as others
chime in corrections and suggestions. Also, if there's duplication, a
commentor should be able to either wipe their comment out, or else
make a note (or set a flag) on it saying it's already been integrated
into another comment (and to use that other one instead).

My todo list is pretty huge, and I've only just recently started
learning rails, but I'm hoping to grab the source next week to have a
look-see.