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
|