One of the most powerful, general, and evolving sources of information
in Squeak is the system organization itself - or more precisely, the
system meta-organization. The system categories and method protocols are
a very powerful and pervasive form of "documentation". To this could be
added further levels of meta-organization. For example: a general
public(by default)/private classification for method selectors would add
a significant level of "noise filtering" - allowing the browsers to be
able to show only the selectors intended for general use without
distractions (if desired). I see this being a level of meta-info about
the method just like its protocol -- I'm not interested in the system
actually enforcing private methods (yuck). You could certainly have more
than just these two levels (and protocols could likewise be tagged
public/private/whatever). A similar scheme could be applied to classes
and even to system categories - in this case they might be called
user/system categories, allowing another level of filtering if desired.
Each of these would also add another level of reflective info for the
system to use.

The fundamental goal of all of this is to impart information in a highly
leveraged fashion while greatly increasing the signal to noise ratio --
you can find what you need to see when you go looking. The immense level
of detail presented in a full-scale Smalltalk like Squeak, combined with
no signposts that point to where to begin (especially if there are no
wizards at hand to help), can make Squeak intimidating to newcomers. I
think the real goal of the documentation effort (after plugging a few of
the more obvious holes) should be to provide the knowledge of where and
how to begin the journey, what you need to pack, and what fun things you
can then do and see along the way. Great wads of detailed static
documentation won't serve a highly dynamic environment like this very
well (or for very long). 

-- Dwight


Edward P Luwish wrote:
> 
> I do not want this to become something like the discussion of "a message is just a subroutine".
> Not only is Smalltalk different from everything else, but the different way one needs to think is the essence of its expressiveness.  Delving through the corpus of code not only suggests how to solve a given problem, it suggests new problems to solve.
> 
> The question is how do we best communicate this, so that our community grows larger and more influential in the world at large.  We have a terrific opportunity, since this project is not only at the forefront of object technology, but also of open source.
> 
> There are experts out there who have some answers.  They have documented why some practices may be better than others, and have discovered some effective educational methods.  I will step back while they offer some suggestions, and as a community we should expand on them, debate them, and come up with a plan for a documentation project.  I will help in any way I can.