As long as the remote comment database would *supplement* comments in the
base image, then I don't see a problem. But hitting the proposed remote
comment server should be optional; there are plenty of occasions that I'm
working on code offline. Code comments should always remain with the code in
the image. This code and its corresponding comments have been reviewed prior
to general release. This review ensures a level of quality that may not be
achievable with the server-based documentation that can be modified by
anyone anytime.

Personally, I have a greater need for documentation that gives me a more
abstract view of how classes and methods interact with each other. When I
want to develop something new in unfamiliar class territory, how do I know
where to start? Presently I have to click on each and every class in a
certain class category reading comments, bring up numerous hierarchy
browsers and flip between them, trying to visualize and juggle it all in my
mind and on the screen.

A graphical "class hierarchy view" would help immensely, as would a
graphical "method interaction view" to show which classes and methods are
being referenced. The views could be accessible from a browser menu and
presented in UML so they are understandable by a wide audience. They would
be generated on-the-fly and would aid understanding without someone having
to manually document how things work. This is documentation that would not
have to be kept up to date nor kept on a remote server.

Chris Becker


-----Original Message-----
From:	squeak-dev-admin at lists.squeakfoundation.org
[mailto:squeak-dev-admin at lists.squeakfoundation.org] On Behalf Of Duane
Maxwell
Sent:	Sunday, January 20, 2002 8:35 PM
To:	squeak-dev at lists.squeakfoundation.org
Subject:	A documentation proposal (non HTML version)

(Sorry about the HTML in the earlier version -- DSM)

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