From: ruby talk <ruby.talk.list@...>
Date: 2005-01-25T04:12:51+09:00
Subject: Re: Ruby WikiDocs?

On Tue, 25 Jan 2005 00:47:33 +0900, Warren Brown <wbrown@isoft.com> wrote:
>     In response to the recent posts on the ruby-talk ML about where
> documentation comments and patches should be posted, I would like to
> suggest a plan to augment the current effort to fully document Ruby:
> WikiDocs.
> 
>     Ruby WikiDocs would basically be a Wiki containing Ruby
> documentation that anyone (after registering?) could add to, change, or
> simply make comments about.  This could be similar to online manuals
> that allow user comments (e.g. http://www.php.net/manual/en/), but if we
> allowed users to change or add to the documentation itself, it could
> grow more organically.  Eventually some of this new documentation could
> be back-ported into the source code.

This is something I have on my growing ToDo list for ruby-doc.org and
has been discussed in the past.  I would like a way for people to view
the API docs along with a way to add comments and corrections.  Im not
sure if a Wiki is the right tool, but it might be.
> 
>     I imagine there would be problems with spam and other abuse, so the
> Wiki would have to be monitored.  I'm guessing someone in the Ruby
> community would have the time and resources to do that.  

As a general rule, nobody has any time or resources for anything,  
Most people contribute to the Ruby community in their so-called spare
time, so it is key that such tools require near-zero maintenance and
administration.

(Spam is generally monitored by site users and fixed by same, though.)

> There would
> also have to be an initial set of documentation placed on the Wiki, but
> I believe that ri could generate the necessary HTML with little or no
> change.  Finally, there would need to be a well defined set of
> documentation standards that updaters should follow, so someone would
> have to come up with that.

No.  It should be as easy and mindless as possible, to encourage
people to contribute, but structured in such a way that what gets
posted  follows some particular format (maybe).  Asking people to
follow some set of documentation standards is too much work for users.

Most people follow common sense and etiquette (at least by looking at
the Ruby Garden wiki), so I don't see a big issue here.  If content is
added to the source code then the doc standards will be applied there.

James Britt