(from another part of the thread)
Thanks for the kind words Adam.

Replying to yourself is bad form, but Paul Fernhout apparently wrote:
> And don't ask them to try and learn the language either, 
> because there's no documented API, and the purportedly 
> self-commented code really isn't.

Actually, the student wrote the above (my mistake in letting it slip by
looking like I wrote it). I was too in too much of a hurry to run
downstairs to see "Star Trek Voyager" which has just started that I
didn't proofread enough before sending.

But to respond to the student's point (which was my intent), there has
been in the past a lack of comments on many key classes in Squeak. Also,
it's not always clear where to look for comments (unlike say with
JavaDoc where you get an entire web page to view at once with important
comments covering a class). I personally like having a "documentation"
method rather than have to press a special button to be in documentation
viewing mode. 

Someone suggested months a while back on the list being able to include
a comment in the class definition -- I like that idea a lot, as opposed
to always reformatting that entry. Also, Smalltalk could have benefited
from a triple quote like Python so that larger example code snippets
quotes can be easily pasted into regular code, as opposed to being
tempted to invent another place in he Browser to put them where code and
comments can be mixed without needing to be compileable. In general,
anything along the lines of literate programming support (mixing code
and explanation) would be nice. 

Squeak has some of this (with picking fonts etc.) and I haven't explored
this as much as I could, so perhaps more can be done already than I have
tried. In general, I like sticking with unadorned text though. It would
be great to be able to mix in XML into code too I guess (a fusion of
code and data -- say for defining window layouts), but this starts down
a more general path for embedding various types of textual
representations, with say embeddable Scheme or Forth mixed with
commentary and Smalltalk and XML and so forth, all happily digested by
various compilers invoked on a fragment by fragment basis.

I disagree somewhat with the student about the self-documenting nature
of typical Smalltalk code, but then again I earlier disagreed over the
value of the keyword syntax. I do however think that complaints about
lack of being self-documenting may have something to do with the excess
complexity of the base system. For example, whenever I try to wander
through Morphic base classes my head starts spinning -- no matter how
well the methods are documented. Because Morphic wants to be prototype
based (coming from Self), it needs extra baggage to fit into Smalltalk
just for a start. But it needs refactoring too, and maybe some trimming
(dropping delegation like aspects in the base for example).

Protocols are not used consistently in this and other Smalltalks. I
personally like using "ing" words for categories preferring for example
"intializing-releasing" over "intialize-release", but I have to also
deal with a preexisting inconsistent naming convention. Unlike
VisualWorks, Squeak doesn't attempt to track protocols to keep you in
the same one as you move around in a browser. That is, in the default
3.0 release if you are in "intialize-release" and jump to another class
the Browser doesn't put you in the same protocol (and ideally select the
same method). And the standard browser in Squeak doesn't remember the
last protocol you were in in and old class to suggest the name for a new
one either.

Changes have been happening so rapidly over the past few months and
there never was a stable base GUI (beyond the too limited MVC). So I can
see how a student would be concerned about there not being a documented
API (in the sense of a book or help file or HTML overview) when it comes
to things like GUI widgets. There is some material on the web, but
obviously you need to match the documentation with the version of
Squeak. Since historically Smalltalks have had minor incompatabilities
in various classes (ANSI anyone?) I can see how these could throw a
student trying to learn from a published reference on Smalltalk (no
matter what Smalltalk). So, Squeak for students could benefit by being
more self-contained in this sense, and it obviously isn't quite there
yet. However, I'm not up to date on what introductory material is out
there on the web, so there may be great resources that didn't connect
with this particular student for whatever reason.

However, in Smalltalk and Squeak's defense, one reason I love Smalltalk
is because the source has been available as a reference in most
versions. When I do Java or Python or Scheme I am always consulting
printed or HTML references or going to Google or DejaNews (now the
same), whereas in Smalltalk I would be looking more in the image. Why
just today I was trying to post a menu event in Java (pays the bills,
sigh) and even with Google and the API documentation I couldn't figure
out how to do it properly in non-deprecated form in the short time I had
to devote to that (even after looking at all the API calls and classes
likely to be involved), so I gave up on that approach and solved the
problem another way. In any Smalltalk system I probably would have had
little difficulty understanding how to do that because I could see how
it was done by the system. 

Having said that, I had to approach Smalltalk several times on several
different occasions on several different platforms (Mac/APDA, Tektronix,
ObjectWorks, ST-V/286) before I started to feel comfortable with it, and
that was mostly after already knowing something about OO from
programming on a Symbolics and on the Mac. Just like the first time I
got a Unix account (~1982) I didn't really "get" hierarchical
directories or understand where things were, and only really "got" them
and the layout of Unix when months later I remembered I had the account
and played around with it some more.

Fifteen years ago I read the results of a survey that concluded the only
thing all excellent Unix system administrators had in common was knowing
how to use the "man" command. One of the reasons Smalltalk testing (for
jobs) is somewhat of a joke is that one of the most important skills of
a Smalltalk developer is someone who can learn how to do things using
the Smalltalk Browser, and that doesn't show up in a paper and pencil
(or online) test. 

But having said that, obviously the classic problem for a Smalltalk
novice is not knowing where to start, and a more modular base system
with more commented base classes with dynamically loadable examples
running on a stable GUI would help. 

I can very much imagine how a student (especially with other courses
etc. in a tough school like GATech) could easily feel overwhelmed having
to jump into using the best of all Smalltalk systems. It has been said
it takes six months for full-time employees (with a background in say
COBOL) to come up to speed in Smalltalk and the typical class libraries.
In the context of a student doing Smalltalk part-time for a semester,
any obvious warts like missing documentation or slow or buggy systems is
going to be a lightning rod for disgruntlement. The bottom line is that
Squeak has good points and bad points, and we as developers must see
them both. We can't pretend the limitations don't exist, because
recognizing them and remedying them is the only way things will get
better.

One issue specific to the situation seems that the course sounded
ambitious -- doing MP3 plugins and handling 240(!) students -- as
opposed to just simple graphics or sounds within the system for a class
of thirty. It's an indication of Squeak's previous success at GATech
that it has grown to this scale. I personally can't imagine what it
would be like to teach Squeak to 240 people at once -- I had my hands
full trying to teach 20 biology majors the rudiments of C/C++ (I found
the ones who didn't learn on their own learned the most when I spent
time with them hands-on in the computer lab to help them over rough
spots, something that won't happen as much in a class that size). Not
knowing the course or the instructor or the student (although Mark
Guzdial mentions equipment & software issues and an instructor new to
Squeak) I can't know exactly what produced the strong negative reaction.
Not every college course can be a great success for everyone, especially
if the instructor has the guts to take risks and try new things. Still,
I feel that despite all its good points (e.g. Mark drawing "oohs" years
ago from GATech students by showing them how to draw a line across and
outside a window), Squeak was undoubtedly partly at fault, lacking for
example complexity management features like those LearningWorks has
sought to add. 

But who knows, with another few weeks in this semester, maybe this
student will change his or her mind, like I did about the value of
hierarchical directories. In any case, school is about learning, and
learning to deal with frustrating technical glitches, poor
documentation, unfairness and so forth while staying pleasant(*) is
(sadly) probably good experience for life. Obviously though, that isn't
what we want the main thrust of Squeak to be about.

By the way, adding better documentation (with examples) to the system
might make excellent class projects at GATech by the way... If I still
taught programming these days I'd try to make as many exercises as
possible be a contribution (no matter how minor) to some open source
effort (even if the students decide not to contribute it after it was
done) as a way to learn by doing and show them the larger context of
their programming efforts. How about telling that student he or she will
get an A in the class if she or he writes good documentation to some
number of classes or methods found confusing? Just think what 240
students working together could add in just one week near the end of the
semester! 

-Paul Fernhout
Kurtz-Fernhout Software 
=========================================================
Developers of custom software and educational simulations
Creators of the Garden with Insight(TM) garden simulator
http://www.kurtz-fernhout.com

(*) A quote from the movie "Harvey": "There are two ways to succeed in
life: to be awfully clever, or awfully nice. I've tried clever; I prefer
nice."