A documentation proposal

Gary McGovern gary.play at btopenworld.com
Mon Jan 21 05:38:38 UTC 2002


No disrespect to you personally Duane, but I remember a similar discussion at Easter last 
year and Dan Ingalls proposed a system of updating the commenting. That seemed to go 
ignored. It seems that once in a while there is a lot of hot air about documentation and 
nothing gets done.

It would be good if no classes were accepted into the image until they were documented. 

A lesson is to be learned that scholars are still trying to find out how the pyramids of 
Egypt were built. ;-).

Gary


21/01/02 00:38:24, "Duane Maxwell" <dmaxwell at san.rr.com> wrote:

>   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






More information about the Squeak-dev mailing list