This is a semi-rant, and I think people are mostly aware of the
issues.  I mostly want to underline their importance (and vent).  I
have a couple of specific questions (3 paragraphs down) about how to
help improve the documentation, and of course I'd appreciate any
pointers on the specific issues I ran into.

squeak aspires to be graspable by a single person.  This person is
finding it very hard.  The multiplicity of models and the paucity of
documentation make working with squeak excessively challenging.

I've seen the note that squeak is in the divergent, exploratory phase
of development, as well as to do lists that included documenting, or
documenting better, methods and frameworks, including some of the
specific areas I ran into.  So please don't take this message as an
insult to the work that's been done, which I appreciate, or to the
community's ability to grasp that there is a problem.

I've also looked at the swiki, which is some help.  But it left a
lot of questions unanswered, and is not a substitute for an adequately
documented image.

Two practical questions: if I understand things well enough to offer
improved class or method comments, what is the best way for me to
offer those improvements?  My "improved" comments probably should be
reviewed by those more knowledgeable.

Second, what is an appropriate way to document frameworks?  By this I
mean groups of related classes that work together (this is a more
modest definition of framework than many others).

Now, on with the details of things I ran into.  This was motivated by
the desire for a seemingly minor tweak in layout within a scrollpane.

Initially I focussed on the layout framework, which has fairly
extensive documentation on the swiki and in online projects.  The
documentation is more from the perspective of someone who wants to use
the framework, rather than modify it.  I found myself constantly
surprised by the behavior I was getting.  Mostly I had to guess what
the various bounds methods did by studying their use, rather than
reading their comments (this particular item is on a cleanup list on
the swiki).  The pre and post conditions and expected useage patterns
were not clear.  

The two stage logic (invalidate and then later layout) made things
more complex (especially for debugging, during which I often managed
to create infinite loops of windows popping up, even when I finally
tracked down where changes were happening).  This two-stage logic is
documented a bit, and I presume there are good performance reasons for
it, so perhaps not much can be done about it.

The logic is also complicated by the fact that constraints flow both
up and down the morph subobject hierarchy.  Again, this is probably
inevitable given the design goals, though a little more documentation
on exactly how it works would be good.

Then, just when I thought I had the layout working, I discovered the
embedding in the scroller was not working well.  This led to the
ScrollPane/ScrollBar world.  Here I discovered that ScrollPane
lacked basic documentation about how it worked (e.g., I couldn't
tell whether various variables were in pixels, fractions of the
displayed screen, fractions of the entire virtual area behind the
scrollpane, etc).

The ScrollPane was a MorphicModel, but after reading the class comment
I couldn't quite tell what that was about.  It referred to the
"world"; did that mean the Model, or the whole window, or something
else?  It mentions objects being "sensitized".  Huh?  It referred to
slots in the world.

At this point, and after looking at some of the scrollbar code (for
example, objects were created with 
scrollBar := ScrollBar new model: self slotName: 'scrollBar'.
where the slotName did not seem to be an accessor to the class, it
seemed likely that some kind of a meta-object system is in use (as I
kind of knew etoys employed), perhaps with methods being compiled on
the fly.

So I seemingly am confronted with another sizeable system to master,
with mastery only available by tracing through the code.

Rather than objects encapsulating complexity, they seem to present an
every unravelling thread of subjects to master.  The complexity is not
encapsulated because the interface and model are not sufficiently
documented.

The ScrollBar class comment said "Inspired by an oiginal design of
Hans-Martin Mosner", but neither google, the list archives, nor the
swiki revealed what that design was.  The rest of the comment
basically said the class was very flexible, without saying how it worked.

And then I ran into this weird problem in which changes did not get
recorded for a duplicate class I created.  More mysteries to unravel.

I'm not saying I can't eventually figure these things out.  I am
saying that it's not much fun--in fact, the whole experience has me
feeling stupid and frustrated.  And I am saying it's harder than it
needs to be.  (Actually somewhat like my experience with Zope, by the
way).

Thanks for listening :)

Ross Boylan