From: E S <eero.saynatkari@...>
Date: 2005-01-25T07:46:19+09:00
Subject: Re: Ruby WikiDocs?

> L�hett�j�: ruby talk <ruby.talk.list@gmail.com>
> Aihe: 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.

I've found that a Wiki somehow works best when unrestricted. For this
purpose, the most important bit would be to make a stylesheet that
allows nice, clear separation between comments and the actual text
(no horizontal rules, please).

For a process like this, however, a Wiki, slightly modified (maybe 
do away with WikiNames and add anchoring (/wiki/Hash#each)) would be the best solution. 

> James Britt

E