I am not sure that this really answers  the question, but what about 
documenting parts of Squeak with UML? (One of my students 
developed a simple UML editor for VisualWorks.) There are surely 
other ways to document, explain, and visualize, but this is one that 
most programmers will be using soon.

Ivan


> Folks -
> 
> Lars Nilsson <lars at cymfony.com> just sent me an interesting message
> basically saying that, as a professional programmer, he didn't find
> the syntax to be that much of a problem, but that the scale of the
> class library and the paucity of documentation and examples were more
> of a barrier.
> 
> I don't want to get (back) into either of these topics here, but it
> reminded me of another related project on my personal list (it has
> fallen off the official list) that might interest some of you, and on
> which I would welcome suggestions or contributions (see the note at
> end).
> 
> Analogous to the task of giving a newbie competence in basic Squeak is
> the question of how to turn a competent Squeak programmer into a "real
> hacker".  I once started on an "archaeologists guide to the Squeak
> image" (I think this actually made it out onto one of the wikis) as a
> written approach.  It would probably be a help at least to finish
> this, but some of our conversations about help for the novice make me
> think there may be a better approach.  Also I have to credit Alan's
> continued insistence that (to paraphrase slightly) "If we do it right,
> it should help the swat teams as well as the newbies."
> 
> What separates a Squeak hacker from a normal Squeaker is, I believe,
> the same kind of thing that separates a competent Squeaker from a
> newbie.  In each case, the expert sees what can't be seen, while the
> novice, of course, does not.
> 
> A competent Squeaker "sees" a whole active structure behind any piece
> of static or dynamic code -- the structure of the objects including
> inherited state, the message interface of objects, including inherited
> methods, temporary variable bindings, the stack structure, and so on.
> 
> What do we do for the novices?  Do we show them a picture?  No.  We
> give them at least three different views (browsers, inspectors,
> debuggers) in a non-pictorial framework, and with no attempt to build
> or maintain any coherence of the picture that they need to understand.
> 
> I have learned from giving demos that one of Squeak's most convenient
> features -- the ability to execute text anywhere on the screen -- can
> be incredibly confusing to newcomers.  The ability to print the value
> of an expression in the debugger is generally understood and helpful
> (except that it dirties the text).  But typing something in the middle
> of a browser pane as an example may seem like utter nonsense if the
> viewer is just learning that this code pane is a view of a method; 
> what on earth is the relationship to the new thread that is spawned
> out of the text editor from the middle of this method that he was just
> beginning to understand?
> 
> It would probably be much simpler if do-it and print-it copied their
> selections to a transcript, and if the results then appeared below. 
> Or at least if there were a pop-up pane for printed results that would
> not dirty the text in which you evaluate an expression.
> 
> The question is:  What are the pictures we use to think with, and how
> can we build them and reinforce them (and not undermine them) for
> newbies?
> 
> And how about the swat teams?  An interesting topic that has arisen
> several times on this list is, "OK, I have SqueakV2.sources (or some
> more current listing of all the classes and methods);  is there a way
> I can just compile it and run Squeak?"  This is what got me started on
> the archeologist's guide.  Here again, there is a picture that the
> Jedi's have in their mind.  They see the process scheduler, the
> display structure, the event handler.  They see the Smalltalk
> dictionary and the shared pools, the changeSets and the project tree,
> the textStyles and text with runcodes for emphasis, changes files
> chunks and remoteStrings.  And Undeclared, the dependents dictionary,
> and obsoleteClasses.  And on, and on.
> 
> What do we do to build and maintain a coherent picture of all this
> structure that is the Squeak image?  Almost nothing.  What could we
> do?  That's the question.
> 
>  - Dan
> 
> [Suggestion:  This is another potentially open-ended topic like syntax
> (the last in this series of "since you asked what we're up to"). 
> Perhaps it will help if, in our discussion, we try to limit ourselves
> to practical items like "the xxx system <url> does a good job of this"
> or "try the attached fileIn for a concrete view of the yyy hidden
> structure in Squeak."]
> 
> 
> 



Dr. Ivan Tomek,
Jodrey School of Computer Science
Acadia University
Nova Scotia, Canada
fax: (902) 585-1067
voice: (902) 585-1467
e-mail: ivan.tomek at acadiau.ca