Re: Standard libraries

>> Here's the modified version of your criteria, that I can accept:
>>
>>   1. newly added things will be canceled if they are not documented
>>      completely before the stable release.
>>
>>   2. when new library is added, let us start discussion about removing
>>      another out-of-date library.
>>
>> 							matz.
>>
>
> [_why:]
> This sounds like an ultimatum.  How long do I have before the next
> stable release?  Do I need to get this done within the next week or
> month?  Also, is there anyone on this list who would work with me to
> document Syck/YAML?  I already have the API largely documented
> (http://yaml4r.sf.net/doc/).

I'll certainly work on it and will work with you.  It's something I had in
my sights (YAML, not Syck), but my time is limited.  I didn't know about
the documentation link, and it looks terrific.

> Furthermore, what are the expectations for satisfactory documentation in
> my case?  How deeply do I have to document the C extension?

I can't give authoratitive answers, of course, but my idea is this:
document the code enough so that users looking at the RI output for YAML,
or at http://www.ruby-doc.org/stdlib/libdoc/yaml/rdoc/index.html, will be
able to get what they need to do some coding right away.  That means basic
introduction and usage examples, and a link to http://yaml4r.sf.net/doc/.

Getting that far is *really easy*.  Getting around to it is, um, ...

The main problem for me as a documenter is deciding what's important. 
Doing some useful examples and intro is pretty easy.  Getting correct and
readable documentation for little-used methods is difficult and/or
time-consuming, especially if I have to work out what they do by
experimentation.  It's the old 80/20 rule.  In this case: the most
important 80% of the documentation only takes 20% of the time.

> I think the recent work on RDoc/Ri is absolutely brilliant and I will do
> whatever it takes to make this work to everyone's pleasure.

That's a good aim :)

Cheers,
Gavin