Re: Ruby Docs with annotations and searching

On 5/17/06, Conor Hunt <[email protected]> wrote:
> > If you make it *too* easy to add a comment, you probably are
> > needlessly setting yourself up for a lot of de-spamming work. (It's
> > possible that the php and mysql folks do quite a bit of housekeeping
> > that we don't know about -- dunno.)
>
> Ok, yes I agree, especially as the site gets larger. Initially thoughI
> would argue that the barrier to commenting should be low to get
> momentum going.

I think that the barrier won't be too big an issue, even at the
beginning.  There are some people lurking about who are interested
enough in contributing that they'd go the extra mile (myself
included).  If you have a lowered barrier to begin with, and then
raise it later on.. you might be putting off your early-contributors.

But that's all philosophy anyways.. who knows what happens in the real
world, or with specific tools/methods.

On 5/17/06, Conor Hunt <[email protected]> wrote:
> I had one idea to help with picking out good comments. Include a vote
> up / vote down mechanism for comments. Then it is easier to pick out
> comments that hit a certain threshold (either up or down) for
> inclusion or exclusion.

I had a similar idea[1], but this introduces the problem that from now
until the system is ready and working (and tested) will be further and
further away, depending on how interesting the mechanics get.

I think that the Ruby docs are a problem to be solved as soon as
possible.  Possibly a big collaborative-documenter project could be
started _after_ a quick "kick in the pants" revision is done.  (i.e.
think like programming.. solve the problem now, then solve it in style
a little later)

An enhanced documentation system would make for an awesome project to
work on though.  (It's on my todo list, but I'm not skilled enough
yet)

The question which should come to mind is.. is there already a tool
out there for this?  It sounds like a no, otherwise something would
probably come to mind immediately.  I'd say use the same software used
elsewhere.. make due while we build something Cool.

[1] http://jrandomhacker.info/The_Self-Moderating_Forum


On 5/17/06, John Gabriele <[email protected]> wrote:
> Another idea to make life easier on the committers: when a commentor
> clicks to add a comment, it would likely be wise to have the resulting
> text field accept RDoc marked-up text. With comments stored as RDoc,
> it becomes trivial for a committer to access that same RDoc'd text so
> they can:
>
> 1. copy-and-paste it into their editor,
> 2. use their editor to add a comment marker (#) to the beginning of
> each line, and then
> 3. save and commit the file.

Automate this more:
* An official documentation admin views the site with links next to
each user's comment.
* Clicking that link displays a popup/whatever with the text already
in commented-form.
* The admin copies the comment as they see fit and paste it into the
edit-view of the official doc (in another window), editing the
official doc online like a wiki.

I happen to disagree with rdoc as a markup language but you're right,
it would be nice to see it used more often and as opposed to the other
markup languages people seem to be using with ruby/rails projects
(like redcloth[1] or bluecloth[2])

[1] http://whytheluckystiff.net/ruby/redcloth/
[2] http://www.deveiate.org/projects/BlueCloth



> Conor previously wrote:
> If I was a committer, I would not try and go through the whole site
> getting a big "doc release" full of updates together on a schedule.
> Instead, I'd do it piecemeal. Pick a module every few days when I've
> got some time, and see what the commentors have to say about it. If it
> looks like there's some good comments, maybe it's time to update the
> docs for that particular module... Hmm... wait -- it gets better.

I completely agree.  It's important to cater to random inspiration..
especially if an admin has a quick "aha" idea.. they'll want to commit
it immediately or they may forget the idea.


> In fact, if you're rating comments, then it's only a small step from
> there to sum all the comment's ratings for a given module and rank
> them on a separate page of the site (The "ripeness" page -- ripest
> modules go at the top). This way, a committer with some spare time can
> take a quick glance at the ripeness page, scoot over to a module
> that's ready for the picking, and update the docs for that module.

Basically there would be an overview of all comments by date,
including the metadata like the karma on each comment.  Like a wiki
"recent changes" page.  Also, to further the voting process, this
feature could be made publically-usable so that others could "patrol".


> Hm... you'd have to then have a comment-specific flag that indicates
> if the comment has been assimilated (by some committer) into the
> source tree. If it has, then it shouldn't count as part of the
> ripeness. Once the RA-Ruby site freshens its content from the official
> source, the comments flagged as already being "picked" should be
> removed from the site (or possibly archived in the compost_heap).

Keep two versions of the docs:
* The officially updated version.
* The last official release with Ruby (purely for historical reference)

A thread marker would exist for the chain of comments.  Set aside the
older comments (for reference/referral purposes) which have been
"borged" into the officially updated version.

I don't want to read the official updated docs, and then read all the
crufty old useless comments before I finally get down to the good
comments which do have something useful to say.  All the old comments
would (presumably) be obsoleted by  the update of the main doc.


> Finally, it might also be nice to have a top-commentor's ranking page
> (Top RubyGardeners!) and also a top-committers ranking page... just
> for fun -- for bragging rights. I know seeing my name in lights would
> encourage me even more to get some good docs in there.

An automated karma system would go far for this.. but this leads to a
strange culture.  I have the feeling that most people who would want
to contribute to docs wouldn't care about bragging rights.  There are
some very powerful speakers on mailing lists, newsgroups and forums,
who appear out of nowhere and post very elaborate solutions to help
out.

For the Ruby docs, I can imagine people whipping up sample code and
helping answer random semi-off-topic comments, etc.. without thought
for reward/fame.

I have a suspicion that the karma game would influence the good-will
game.  While it's an interesting concept, it's not really necessary.
I feel it's somewhat childish.. even posting statistics like how many
comments people have made.. is a turnoff for me.

With karma and rankings the new people who may have something
interesting to say may not want to post, especially in response to
some 30,000th-post poster.

I'd say no ranking, just names.  Just like mailing list posts.. it's
just people commenting.  Some people remember oneanother and mentally
rank, some people don't.

I say no ranking just for this kind of project.. where presumably the
audience is quite adult and the focus for conversation is quite
narrow.  It would be obvious when a comment is excellent or not, and
noise would be obvious without needing to be voted on to make it so.



Phew!  Pardon the long post.. it seems I still have some strong old
feelings about this sort of thing.