Documentation, more, more

mwgrant2001 mwgrant2001 at yahoo.com
Wed Sep 10 05:17:05 UTC 2003


Hi Daniel and Stef,

I thank both of you for your responses. Stef, I am looking at the 
book you recommended. Daniel, as I reread you response I found your 
comments more thoughtful and my comments more vague. You certainly 
have sharpened things. Thank you.

Now back to the dialog...

--- In squeak at yahoogroups.com, Daniel Vainsencher <danielv at n...> 
wrote:
> mwgrant2001 <mwgrant2001 at y...> wrote:
> '> much of what i see at the squeak internet sites is interface
(plugins,
> 
> > widgets, morphs) or multimedia related. just the reason i don't 
like 
> > windows---widgetitis compounded with gadgetitis. 
> Good point. I guess we expect people to learn Smalltalk from general
> Smalltalk resources (books, free or otherwise). What information do 
you
> think is missing, exactly? where should it be in the Swiki?
>

The expectation that people would learn from general Smalltalk 
resources is reasonable. And the effort of the Squeak developers to 
provide some of these materials is notable--Stef's online library is 
substantial. Certainly, the mechanics of creating classes and methods 
is easily extracted from these materials and Guzdial, Korienek, etc. 
if one can't find the mechanics there, then perhaps one should occupy 
oneself with something other than smalltalk. That is, we can't expect 
developers to teach us everything or code for us. I just thank you 
for your efforts.

Now, the things that I think missing are the details how to CREATE 
something useful or viable with Squeak. That is: "here is 
this 'thing' I created in Squeak; here is why I used Squeak or 
Smalltalk as opposed to Java or Lisp or whatever; here are the 
classes and methods I created and WHY I gave then the behavior that I 
did; here are the places that I put these classes in the Squeak 
environment; here is a modest little interface to help you interact 
with the 'thing'; and of course, here is what this Squeak 'thing' 
does."

John Maloney's Bank Account tutorial is an micro-embryonic form of 
the kind of examples I am talking about. Ted Kaehler's Dolphin book 
is way too much in THIS CONTEXT. I'm thinking about 15-20 pages in a 
nice pdf file that covers a project from alpha to omega. 

Now am I asking the Squeak community to write these for me? No! Of 
course not. What am saying, however, is that I believe that such mini-
project--projects that do something--would be great aids to Squeak 
novices, particularly with experience in other programming languages. 
I readily admit that when I code--and particularly in a language I am 
learning--I use and modify other people's code with great zeal and 
not a trace of shame. I learn as I do that and I imagine the rest of 
you have done the same.

Where should these projects be in the Swiki? I don't think they 
should be in the Swiki. They should be nailed in place a click away 
from the Squeak homepage. The R project that I mentioned before has a 
very good approach to documentation. In particular there is 
a 'contributed' documentation pages and a newsletter. They have 
proven to be invaluable for mingling the expertise of the developers 
with the users, and they have attracted contributors not on the core-
team. Check it out. Here is the link:

  http://www.r-project.org/


> > the 
> > rigidity and size of the class structure is definite an 
impediment to 
> > learning smalltalk. smalltalk is almost crystalline and it is 
already 
> > so big. i envision myself falling into a woody allen-esque 
neurotic 
> > paralysis, unable to act on any matter as i worry over where to 
put 
> > any classes i might develop! 
> Please elaborate. What is complicated? 
> - having to use classes (and deciding what to call them?)

No, naming classes is not an issue. If one can't name the classes 
then on probably can't formulate a problem anyway.

> - having to place classes in class categories?

No, this is housekeeping. I'm not THAT lazy! 

> - finding your way in all of the existing class categories?

There are tools, but I do get tired of scrolling. (Still, I really 
haven't done enough experience to comment of this (see next item). 

> - something else I can't even guess?
> 
How about where to put my classes. I know from my (limited) 
experience with LISP OOP (xlisp and CLOS) that my applications tend 
to have complex objects with complex behaviors--they really seem to 
become little agents for me. I always have subclasses. How do I 
figure out the best place to put them in Squeak? I have no feel for 
this issue. Or is it an issue? If one looks at the work of others, 
are there rules of thumbs for deciding where to put classes in a 
particular smalltalk environment? Or does everyone just make some 
sort of proto-objects as subclasses of the Object class and then 
create the desired behavior via the behavior of the attributes 
(variables objects in their own right) of these proto-classes? These 
are the things I want to know. Just a little folklore would be nice.


> > consider winston's 'on to smalltalk'. a prescriptive book, good 
for 
> > many but not all, winston is wed to 'ste'. but what if it were 
> > updated using squeak? guzdial's books certainly can help one put 
> > one's arms around the whole of squeak at some moment frozen in 
time, 
> > but much of the effort seems to be expended on the interface and 
all 
> > the different goodies. kaehler's dolphin book is definitely 
a 'how-
> > to' book but now we have the dolphin interface. and so on. my 
point 
> > is that significant time must be invested on environment specific 
> > features when learning any smalltalk implementation. 
> IIUC, the problem is that Smalltalk books are 
> - dialect specific
> - focused on the environment, which is again dialect specific.

Yes

> 
> This stems from Smalltalk being designed from the ground up as
> language+library+environment. 

Sure.
> 
> Which of the free books (or others) do you consider the best one for
> learning the language/libraries/environment as present in 
Smalltalk? 

Let me think about this, and maybe answer later. A broader discussion 
on books may help others on the forum? 

> 
> > i also found learning r to be much more easy than squeak.
> [books]
> > probably none, but if one changes 'books' to 'learning material 
and 
> > resources', i counter with: compare the r project with squeak and 
its 
> > swikis. and what about python.org? 
> Please do compare them. We're not very familiar with them. Can you 
be
> specific and give pointers to the most useful elements?

I gave you the link to R above. In my mind the R foundation sets the 
standard for everyone else. First, a little background on R and the R 
project. R is a a GNU variant of S, a modern vectorized language with 
a penchant for interactive exploration  of data. R goes toe-to-toe 
with the commercial S implementation, S-plus. R, like Squeak, is 
developed by an international core team, most if not all of whom are 
in academia or in a corporate research position. R is multi-platform. 
There are many contributors on and outside the core development that 
contribute substantive, documented packages to R. And like Squeak, R 
has a vigorous help forum.

A big difference between R and Squeak is that R has strict, 
established protocols covering implentation and documentation of 
contributor packages. This means that it fits seamlessly into R. 
Another big difference is in the organization of the two sites (R-
project and Squeak.org). I believe that the differences may be 
attributed to a very strong focus on quality in the R organization. 
Keep in mind that most of these people are practicing statisticians 
and scientists, where quality requirements can be very, very high. 

The Squeak site, Swiki and resources reflect more of a bleeding edge 
culture. Squeak is an exploration of an alternative computing 
environment and it is an ongoing experiment. One effect of Squeak 
being an experiment is that it is a perpertual prototype. 
Documentation is often missing in prototypes. Afterall coding is more 
fun than writing.

One can never expect Squeak to have the polish of R. Different folks 
are involved with different missions. However, there is a clarity of 
presentation at the R site that can not be ignored. The Squeak 
information on the internet does not have to be so unorganized. I 
would definitely rethink the ROLE of Swikis. IMO they are too 
prominent in Squeak culture. Squeak needs more accountably and 
conciseness when interacting with the outside world, if the Squeak 
community wants to move beyond being an experiment. 

> > finally,when all is said and done, i believe that the squeak 
> > community is a raucous community because it wants to be and that 
to 
> > me is part of its charm. exploring the cutting edge requires the 
> > freedom to explore--the rest of us will just have to accommodate 
that 
> > or find an vehicle. moreover it would be enjoyable to contribute 
some 
> > day. i'll work on that.
> That's good to hear. As you might have understood from above, I at 
least
> do think that we could quite easily leverage our documentation more
> effectively, and create a situation where Squeak is about as easy to
> enter as Python. Your help would be appreciated.

Yes, I think it is possible (and desirable) to make entry into Squeak 
much easier. 

As for my help. OK, I'll do what I can. In my way, or do you have 
some specific needs? 

> 
> Daniel

Best regards,
Mike



More information about the Squeak-dev mailing list