Asp Forum - Ruby WikiDocs?

Warren Brown

1/24/2005 3:48:00 PM

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.

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. 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.

I will be the first to admit that this might not work for various
reasons, but I also think it would be a good experiment to try it and
see what happens.

Comments anyone?

- Warren Brown

4 Answers

ruby talk

1/24/2005 7:13:00 PM

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.

James Britt

John Wilger

1/24/2005 10:05:00 PM

On Tue, 25 Jan 2005 04:12:51 +0900, ruby talk <ruby.talk.list@gmail.com> wrote:
> On Tue, 25 Jan 2005 00:47:33 +0900, Warren Brown <wbrown@isoft.com> wrote:
> > 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.

The real sweet spot, of course, would be to figure out how to automate
the backporting of the contributed documentation into the source
comments. Then it might actually happen. ;-)

--
Regards,
John Wilger

-----------
Alice came to a fork in the road. "Which road do I take?" she asked.
"Where do you want to go?" responded the Cheshire cat.
"I don't know," Alice answered.
"Then," said the cat, "it doesn't matter."
- Lewis Carrol, Alice in Wonderland

James Britt

1/25/2005 1:04:00 AM

John Wilger wrote:
>
> The real sweet spot, of course, would be to figure out how to automate
> the backporting of the contributed documentation into the source
> comments. Then it might actually happen. ;-)

Well, short of some AI that verifies the content for correctness, even
per-class RSS feed might help the code/doc owners keep tabs when someone
has commented.

James

>

John Wilger

1/25/2005 12:47:00 PM

On Tue, 25 Jan 2005 10:03:40 +0900, James Britt
<jamesUNDERBARb@neurogami.com> wrote:
> John Wilger wrote:
> >
> > The real sweet spot, of course, would be to figure out how to automate
> > the backporting of the contributed documentation into the source
> > comments. Then it might actually happen. ;-)
>
> Well, short of some AI that verifies the content for correctness, even
> per-class RSS feed might help the code/doc owners keep tabs when someone
> has commented.

I wasn't thinking quite _that_ automatic. More like: the
documentation---after being reviewed by someone with appropriate
authorization---could be added back into the source file in the
appropriate place with the click of a button. Basically just something
to keep the maintainer from having to retype the information. DRY.

--
Regards,
John Wilger

-----------
Alice came to a fork in the road. "Which road do I take?" she asked.
"Where do you want to go?" responded the Cheshire cat.
"I don't know," Alice answered.
"Then," said the cat, "it doesn't matter."
- Lewis Carrol, Alice in Wonderland

comp.lang.ruby

Ruby WikiDocs?

Warren Brown

ruby talk

John Wilger

James Britt

John Wilger

x Login to ForumsZone