Re: Ruby Docs with annotations and searching

On 5/18/06, mathew <[email protected]> wrote:
> [snip]
>
> Rdoc makes it ridiculously easy to write at least minimal documentation
> while writing the code. If the people updating code are so misguided or
> lazy that they won't jot down a few lines of comments while they've got
> the code open in their text editors, they're not going to go to some web
> site and navigate around to the right place and write it there.

Right. But a small percentage of users may head over there after they
learn something to put that info up for others to benefit from --
especially if it's as easy as hitting a "comment" button and just
jotting something down that's fresh in their mind from just having
worked on it.

I'll admit it's not the best way to get docs -- to have the users
struggle and write them themselves. But if the process is streamlined,
made fun or even customary, it might work out well. (Imagine on
ruby-talk after someone figures out a quirk with a given module. A
post might then be, "Now that we've figured this out, could you drop a
note about it on RA-Ruby?")

> The
> people going to the web site will mostly be people who don't know how
> the code works.

Well, if you visit, then that'll make at least one who's interested in
getting some of the submissions/comments into the official tree. :)
Maybe others would do so too.

> Hence my guess is that an "annotated Ruby documentation" site will fill
> up with questions.

You could always state that the policy is to only put comments in that
you think will be useful to the community.

> Yes, it may attract some people who take the time to
> answer the questions, but basically it'll be another ruby-talk, only
> scattered across thousands of web pages.

It seems to me that it would turn into something complementary to
ruby-talk. You ask your questions on ruby-talk, sort out the issues
you're confused about, and then some percentage of the community heads
over to the RA-Ruby site to jot down what they've learned.

Also, the "thousands of web pages" would happen to be conveniently
organized by Ruby module. :) You can go straight to the one you're
interested in.

If the same sort of docs ended up in a wiki, they'd tend to be
haphazardly organized. If they just stayed buried in the ruby-talk
archives, then you've got to search for them all scattered about.
Conor's solution seems to be a pretty good idea.

> 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.

> So what's my alternative? Simple: instead of spending time getting this
> web site off the ground and managing it, use that time to write some
> documentation.
>
> It seems to me that everyone wants to build fancy new documentation
> processors and fancy documentation web sites so that *other people* can
> write documentation; the problem is, *nobody wants to actually write the
> documentation*. Prove me wrong, sit down and write some.

Well, it might not be "nobody"...

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.

> Pick a library, ideally one you've used. See if the source code has some
> comments, a README, some examples, or any other starting points. If the
> source is impenetrable, fire up irb and toy with the library until you
> work out what it's doing. Ask for clarification or assistance on
> ruby-talk or on this list.
>
> If you have to, leave bits of the library undocumented. There's no shame
> in doing an incomplete job, it's better than no job at all. For
> instance, I skipped net/ldap when I did net/everythingelse, because I'm
> quite happy to admit I know practically nothing about LDAP and have
> always found it impenetrable.

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? Then, after the page o' comments has had some time
to stew in its own juices, *then* you could confidently post your
patch (and, presumably get committer access after doing this a number
of times).

BTW, it just ocurred to me one other useful feature: it might be nice
if there was a way on RA-Ruby to get dibbs on a given bit of
documentation that you plan on submitting a patch for (or doing a
commit). Conor, if your goal is to get polished extracts from the
comments into the official docs, then individuals may want to "take
ownership" of a given module. I.e.: something like a note on the page
saying, "so-and-so will likely do the commit for this module, when
it's ready."

That might avoid some possibly uncomfortable situations where 2 users
attempt simultaneous commits. It might also help avoid no one wanting
to touch a given module because they think someone else is planning on
doing the commit.

> Of course, if you want to go ahead with the web site, I've nothing
> against that. I just don't think it'll be as productive a way to
> generate documentation as actually writing documentation. If I'm wrong,
> that's good too.
>
>
> mathew
>

Mathew, my guess is that by:

A. lowering the barriers to entry to get started,
B. allowing your doc additions ("comments") to be peer-reviewed for a
little while, and
C. pooling your comments with others from different folks,

some new magic might happen that we don't see happening right now.
Might be worth a try anyhow.

(And now, ... with apologies to Arlo Guthrie...  )

You know, if one person, just one person, puts up some good comments
and submits a patch to ruby-code, the folks there may think she's
really sick and they won't take her patch.

And if two people do it, in harmony, they may think they're just
fooling around, and not take either of their patches.

And if three people do it! Can you imagine three people walkin' in to
ruby-code, posting doc patches, and walkin' out? They may think it's
an organization!

And can you imagine fifty people a day? I said FIFTY people a day . .
. walkin' in, submitting doc patches, and walkin' out? Friends, they
may think it's a MOVEMENT, and that's what it is: THE R-ANNOTATE
ANTI-MASSACREE RUBY-DOC MOVEMENT! . . . and all you gotta do to join
is to sing it the next time it comes around on the guitar.

With feelin'.