<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
