Asp Forum - Re: Ruby WikiDocs?

e

1/24/2005 10:46:00 PM

> 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/...), 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

comp.lang.ruby

Re: Ruby WikiDocs?

e

x Login to ForumsZone