Re: Could Ruby-doc be better? -- Proposal for a better system.

Hugh Sasse wrote:
> I'm not on ruby-talk at the moment so I'm not copying to there.
> Feel free to copy it if you wish.
...

> > 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.
> Why?  Editing the rdoc comments in the source code is probably
> easier than using the web for this (better editor, easier to browse
> code, etc), and creating patches is not difficult, it's just diff -u.
>
> Or, maybe you are saying there needs to be a more formal statement
> of how one submits documentation changes, so that people know how to
> do that?
>
> > 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
> I'm completely unfamiliar with PHP, so that means nothing to me.
> What are the salient features?
>
> What do you perceive as the barrier that needs to be lowered?
The PHP site has an on-line API manual that is similar in appearance to 
th stdlib pages on ruby-doc, but readers can add comments at the bottom 
of the main window.
It serves two purposes. One is for readers to easily point out an error 
or typo or some such thing.  The other is to provide examples and 
observations on using a given library.
What I like about it is that is is fairly simple to do; the barrier to 
contributing is quite low. Currently, if someone finds a mistake, they 
have to write it up, send it someplace, hope it went to the right place, 
and wait for it to get merged into the source, and then wait for it to 
appear in the next iteration of API docs.  Long-term, most of that stays 
the same: doc changes still have to get sent to someone for review and 
CVS merging, and they eventually find their way back to the republished 
docs.  But with the PHP.net format, such comments and corrections are at 
least readily viewable to other readers while things work their way 
through the system.  (But this brings up another matter: who would take 
responsibility for reading over comments and getting the appropriate 
items into the Ruby source?  It's a thankless task, really. )
The more interesting aspect is allowing people to post examples or tips 
or pitfalls, things that are unlikely to ever go into the source code 
comments.
BTW, it is fairly simple to write an rdoc template that adds a link to 
each page that goes to a corresponding Wiki page.  The API docs could be 
linked to the wiki on rubycentral.org.  It would not be all slick and 
in-line as on PHP.net, but it's low-hanging fruit.
...


> > I'd imagine the system would work as follows
> >
> > Checkout latest CVS ruby code
> Which one?  1.9, 1.8.3, ....  That's part of the problem.
Indeed,but  let's assume the presented docs were the current release. 
(Still, it would be nice to have a central doc system that allowed for 
language versioning.)
> ...
> > The comments would probably be fairly straightforward, no registration
> Wiki spam?
I would go for a comment system that did not allow any markup; certainly 
no links,as they are not needed .   But that's a side issue that needs 
to be considered.

James