<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<META content="MSHTML 5.50.4912.300" name=GENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY bgColor=#ffffff>
<DIV><FONT face=Arial size=2>I've been giving some thought to the Squeak
documentation problem, and I'd like to make a proposal and get some
feedback.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>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.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>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.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>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).</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>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.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>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.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>I will do the backend if someone will do the
frontend. Others can also mirror the database in the event of a
catastrophic failure.</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>Comments?</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV><FONT face=Arial size=2>-- Duane</FONT></DIV></BODY></HTML>