All:

Well, I can't find the note I was going to respond to, so I'll reply to
myself. ;-)

I am afraid that I do not have much time to help with documentation, and
I don't know enough to do anything about Morphic, but, FWIW, here are my
short wish lists.

Morphic:

Andreas mentioned kids learning Morphic and likened us all to them. I
like that comparison. I also think that it is a good way to approach an
object oriented environment. Play around, experiment, and even break
something from time to time.

In my brief experience with Morphic I was pleased with how easy it was
to build a Morph that at least looked like what I wanted. But I quickly
found that it was not easy to get it to act like I wanted. But exploring
the Morph I had built gave me a head start on creating a Morphic
subclass to do what I wanted. A large part of what I wanted to do had to
do with communicating with other objects. Maybe I missed something, but
that seemed to necessitate writing some methods, and that meant a
subclass.

Since I have had some experience with Smalltalk before, that seemed
natural, but I wondered how necessary it should be. If you can build a
Morph or Morphs for an application, why bother with writing a class to
create it or them? (I think that's one of Andreas's points.) But then,
why shouldn't Morphs have communication skills? 

So that is first on my short wish list for Morphs: good communication
with other objects. I know that's vague, but that's something I felt a
need for.

Even bigger on my wish list for Morphs also has to do with learning
about an environment, and either our early learning or something that is
genetic. Much of what we learn as children about the world may be
considered conservation laws. What things stay the same during change?
For instance, the amount of a liquid stays the same even when you pour
it into a different shaped container. One thing that we learn very early
or in hard wired is that solid things retain their shape (more or less).
As they approach us or recede from us, they appear larger or smaller,
but their shapes stay the same. 

What does that mean for the Morphic world? It seems to me that either
the general default for a Morph should be to retain its shape under
resizing, or that should be easily achieved. Then Morphs would act more
like we have come to expect real objects to act, and that would provide
a psychological advantage for both programmers and users.

That does not now seem to be the case. Others have mentioned weird
behavior of Morphs under shrinking. Let me add that the ChessBoard
crumbles under expansion.

So my second wish is for the conservation of shape under resizing.

My third wish has to do with going from Morph (prototype) to more fully
functioning object. That means either being able to add functionality to
a Morph without subclassing, or, if subclassing is necessary, moving
smoothly to the subclass, automating the process as much as possible. I
know that's a lot to ask, but hey! it's a wish list. :-)

Documentation:

As I mentioned earlier, I think that playing around is a good way to
learn about an object oriented environment, and that's how children
learn, in large part. But they also learn by instruction. I feel that I
have had to experiment too much with Smalltalk, because of inadequate
documentation. The following is my personal opinion, but maybe it will
strike a chord.

I think that code should be self-documenting, for the most part.
Sometimes low-level comments are necessary, but normally code can say
what it means, at a low level. Often that is a matter of good variable
names. (One thing specific to Smalltalk is that if a method does not say
explicitly what it returns, say so in a comment. Experienced
Smalltalkers may not need it, but doing so will help everybody else, and
what's the harm?) So if code is hard to read, maybe it needs a rewrite
instead of a comment.

Where I most feel the need of comment is at higher levels. I want to
know why and what for. It is good to write code that is more general
than the intended use, and so a fairly abstract explanation of a class
or method is appropriate, but it helps human understanding (at least
mine) to have some concrete examples, too. 

I find that Squeak is quite good, in general, with class comments. There
are exceptions, OC. For instance, I find no clues about SkipLists. Where
it seems deficient, to me, is with class examples. I, for one, would
find them very helpful. And besides, they make good tests, don't they?

Thank you for your consideration. I hope this is of some help.

Best to all,

Bill