Hi Duane,

I was working on a special documentation SWiki which will generate
documentation form pages from the comments inside and update the comments
within itself with the web interaction. It is not ready yet and with my load
won't be ready at least until after we released the big double issue but it
seems a very promising tool for collecting and updating class and method
comments as well as comments for class and method categoriescategories and
variable comments. Updating other images becomes a matter of saving the
change set and loading it from other images. Unfortunately as is it is prone
to crash because it keeps changing itself . There are some issues including
security issues we we haven't even begun to address but I believe all of
these can be addressed.

With category comments this information can automatically be turned into a
quite detailed reference manual that can be ( Dandelion can already do that
and we will soon have more tools! ) automatically generated each time it is
needed from Squeak directly. Keep tuned for more fancy toys!

Can you host SWikis in your machine?

I may as well make the announcement for our on-demand publishing venture in
the next email.

Cheers,

Tansel

----- Original Message -----
From: "Tim Rowledge" <tim at sumeru.stanford.edu>
To: <squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, 20 January 2002 9:07 PM
Subject: Re: A documentation proposal (non HTML version)


> "Duane Maxwell" <dmaxwell at san.rr.com> is widely believed to have written:
>
>
> > 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.
> Possibly interesting extensions:-
> a) make sure that whenever a release is 'pickled' it picks up all
> authenticated comments and thus makes the release as up to date as
> possible. This will reduce traffic and improve the image - and be a sort
> of mirror to boot.
>
> b) how about making the same mechanism a door to larger documentation
> (ie tutorials and general swiki info) of a system explanatory nature.
> Class/method comments are deliberately local and cannot explain the
> entire system or subsystem.
>
> tim
> --
> Tim Rowledge, tim at sumeru.stanford.edu, http://sumeru.stanford.edu/tim
> The world will end in 5 minutes.  Please log out within ten minutes.
>
>