I like the idea, but I think there should be a separate "documentation"
Swiki used for this purpose.  This way, we could easily change out the
Swiki backend in favor of something that enables documentation updates
to feed back into the update stream.

The class comment only needs to have a link at the top that reads
"Search for online documentation" (or similar).  That link would take
you to the documentation Swiki and search for (or create) a page for
class documentation.

- Stephen

Doug Way wrote:

> I guess I've mentioned this before, but one simple solution 
> would be to have an automatic link of some sort (or perhaps a 
> menu item) from the class comment in the Squeak browser to 
> open scamper on a corresponding swiki page about the class.  
> This way, the swiki page could have more recent class 
> comments if available, easily editable by anyone, as a sort 
> of backup to the class comment in the image (which as we know 
> is often missing completely).  And this backup comment would 
> be easily accessible from the class browser.
> 
> However, we'd need a reliable way to specify a swiki page 
> based on its name. 
> Something like http://minnow.cc.gatech.edu/squeak?page=Morph 
> should access the page "Morph" on the swiki.  Right now, you 
> can try something like 
> http://minnow.cc.gatech.edu/squeak/morph but it doesn't work 
> reliably (as in this case).
> 
> I'm submitting this an an official ComSwiki enhancement 
> request this time, if anyone feels like adding this feature. :-)
> 
> - Doug Way
> 
> 
> Eddie Cottongim wrote:
> > 
> > I had really only intended the swiki page to be a temporary 
> work area. 
> > But I do like the idea of some kind of linkage between internal and 
> > external docs.
> > 
> > It would be nice if there was a way for the swiki to 
> directly reflect 
> > the comments in the image (like javadoc but more 
> dynamically bound), 
> > have a way to annotate them, and provide a way that people could 
> > harvest updated comments to go into the image. Something 
> like, "show 
> > me all the class comments people have annotated/updated 
> since #5183", 
> > and the harvester would pick the ones he/she thought were 
> improvements 
> > for inclusion with the image. --I don't think you'd want the new 
> > comments to go in the image directly/automatically. Too 
> easy for junk 
> > to get in that way. --Need to work out the semantics of 
> what happens 
> > when the image comment is
> > updated: Probably the comment text would be updated, but 
> old annotations
> > would stay.
> > 
> > Maybe someone did that already. Just an idea.
> > 
> > Eddie
> > 
> > ----- Original Message -----
> > From: "Brent Vukmer" <bvukmer at blackboard.com>
> > To: "The general-purpose Squeak developers list" 
> > <squeak-dev at lists.squeakfoundation.org>
> > Sent: Thursday, February 27, 2003 11:38 AM
> > Subject: RE: [ENH][DOC] MorphClassComment-efc
> > 
> > Looks great.  What about putting a hyperlink to the Swiki page for 
> > this class comment( assuming that page is up-to-date ), within the 
> > class comment?
> 
>