<Sorry for the crosspost, but I thought I might as well try to reach as 
many people as I could :) >

Hello Everyone,

I've been toying with ruby for the last month or so and I've become a 
big fan of the language. My only gripe is the documentation is, at best, 
patchy and obtuse.

I don't intend to flame, or disparage the work done on the documentation 
so far, but its not really up to scratch when you look at Python's 
manual or, my personal favorite, the PHP manual.

I'm thinking of a system that will allow people to edit/add 
documentation from the web based on the existing rdoc and source code 
comments, and then generate CVS patches based on those changes which we 
can then send for inclusion into mainline.

I've been looking at the rdoc comments in the standard library, and it 
seems fairly standard, the method used to document the core .c files 
seems a bit less clear, but I think its still usable.

My basic plan is to have a php style manual 
http://www.php.net/manual/en/ generated from the rdoc comments, with the 
ability to have the documentation maintained in a wiki based fashion, 
and have user comments along the lines of the PHP manual. This way we 
lower the barrier to writing documentation, allow users to comment with 
code samples or additional info, and hopefully increase and improve the 
amount of documentation ruby has.

I'd imagine the system would work as follows

Checkout latest CVS ruby code
Extract the Rdoc comments
Check for conflicts with with the documentation already in the system 
and mark them for manual merging(where the documentation has changed in 
CVS since last checkout)
Rinse and repeat
...

And whenever we think we've made enough progress we can generate a CVS 
patch to be merged into mainline. I think we'd probably maintain a 
'frozen' and an editable version of each item of documentation, the 
frozen is the one shown to casual users and the one we use to generate 
CVS, the editable one is the one contributors edit, and periodically one 
of the moderators would update the frozen version from the editable one. 
This way malicious edits don't screw up the publically viewed 
documentation, and we can control when a particular item of 
documentation goes into CVS. Users would have to register/login to 
edit/add documentation.

I'd also think we could generate 'stubs' for undocumented functions when 
we parse the code, and flag them as being empty and in need of 
documentation.

The comments would probably be fairly straightforward, no registration 
required. The PHP manual has some great comments that help a lot with 
common problems people experience using that particular function. I 
think this would be a valuable addition.

I haven't planned out the technicalities of it yet, but I'm thinking 
Ruby on Rails (Everyone seems to be talking about it, but its ruby, so 
how bad could it be?) and MySQL or PostgreSQL (whatever's handy). The 
apache mod_rewrite might be handy too, but not essential.

Now, I'm willing to take a stab at this (I'm not just talking), but I'd 
like to throw this out there for ideas or comments or flames (stony 
silence aren't quite as welcome or helpful) and to see if anyone else is 
interested in helping with this project. I'm relatively new to Ruby and 
I know nothing about Ruby on Rails, but I'm confident it can be done. 
(Maybe not well, maybe not quickly, but it can be done.)

Anyway, let me know your thoughts on this.

Andrew