I've been giving some thought to the Squeak documentation problem, and I'd like to make a proposal and get some feedback.

As I see it, one of the major disincentives to documentation of classes and methods is that the changes do not readily propagate among the Squeak community - you must provide a changeset, post it to the list, have the bots pick it up, and hope that it somehow makes it into the official update.  For trivial changesets that simply modify comments and so on, the burden is too high for someone to bother.

So how do we propagate trivial changes to documentation of a huge pile of little things?  Perhaps we can learn from a similar system:  CDDB/FreeDB, which collects titles and track names of audio CDs and distributes them to player clients.

I have a couple of Linux/Apache/PHP/MySQL servers sitting on a T1 line, and control over the "squeak.info" domain (please DON'T hit it - it's currently pointing to a little Mandrake machine on my home cable modem).

I will host a shared database of class and method comments.  Someone (not me) can modify the browser to make it trivial to submit comments to the database, and retrieve existing comments.  Submissions would require registration and authentication (to avoid insane people) and a throttle would control the rate of submissions to human scale (to avoid insane clients).  Access to the information in the database would be open and unrestricted, and transparent to the user of the modified browser.

The idea is to make it so easy to submit comments to the system as to be something worthwhile to do while browsing code.  If a comment is not available for a method or class, a simple click of a "document this" button allows a submission.

I will do the backend if someone will do the frontend.  Others can also mirror the database in the event of a catastrophic failure.

Comments?

-- Duane
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20020120/a2fa41d5/attachment.htm