----- Original Message -----
From: Sean McGrath <sean at manybits.net>
To: <squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, January 20, 2002 9:54 AM
Subject: Re: Learning Squeak

> On Sun, 20 Jan 2002, Jim Benson wrote:
>
> [Large snip of things I agree with]
>
> > To me, the Squeak image itself should be the source of the documentation
> > answers. People should be able to ask the image to teach them how to use
it.
> > Unfortunately, it's been so long since I've been a newbie, that I don't
> > remember what type of things the image needs to teach people in order to
get
> > them to 'learn' Squeak.
>
> I imagine a Squeak that embodies Knuth's 'Literate Programming'. We could
> evolve tools that support and encourage writing and reading in natural
> (human) language along side Smalltalk code. To learn, I start with the
> browsing tools in 'narrative display' mode and when I want to see
> implementation I push the 'code display' button.

This was done once before in either ObjectWorks or VisualWorks.  Look for
"Literate Smalltalk Programming Using Hypertext", by Kasper Østerbye.
However, I don't think that the code was made available ( if it had been, I
would surely have archived it back in my pack-rat days ).  Still, perhaps it
might be found at the UIUC Smalltalk archive.

Keeping documentation consistent with an evolving code base is a bit hard.  In
Squeak, class comments don't get very much attention, probably as much due to
the way the browsers operate as anything else.  In order to see a class
comment, you have to do a small bit of extra work, whereas to see code all you
have to do is make a few mouse clicks that are probably nearly instinctive to
the Squeak programmer anyway.  If the browsers were configured to show the
class comment whenever reasonably possible ( for instance, perhaps any time
that a class is selected but a method is not ) then maybe they would get more
attention.  As an example, I've attached some methods for Browser that I just
wrote for Squeak 2.2 that do something like this.

I think that once class comments are given more apparent visibility, then one
might start thinking about attaching meta-information ( computed or manually
created ) to things like system or method categories, as well as to methods
and classes.

Later on, perhaps another route to this would be through Aspect-Oriented
Programming, for which AOP/st ( or similar name ) has been written for
VisualWorks.  Perhaps the documentation could be another thread to weave
alongside the code.

- les

-------------- next part --------------
A non-text attachment was scrubbed...
Name: Browser-defineClassnotifying.st
Type: application/octet-stream
Size: 637 bytes
Desc: not available
Url : http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20020120/0b0181b1/Browser-defineClassnotifying.obj
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Browser-contents.st
Type: application/octet-stream
Size: 1220 bytes
Desc: not available
Url : http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20020120/0b0181b1/Browser-contents.obj
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Browser-basicDefineClassnotifying.st
Type: application/octet-stream
Size: 1140 bytes
Desc: not available
Url : http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20020120/0b0181b1/Browser-basicDefineClassnotifying.obj
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Browser-selectedClassOrMetaClassDefinition.st
Type: application/octet-stream
Size: 493 bytes
Desc: not available
Url : http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20020120/0b0181b1/Browser-selectedClassOrMetaClassDefinition.obj