Help - Background - Remarks - Good documentation

Previous - Remarks - Next

What is definitely necessary, both for Squeak and for Smalltalk, is a good documentation - and one that does NOT give animistic metaphors for facts, nor one that confuses the six levels of <user's mind, user's code, machine's code, machine's hardware, external behaviour of things modelled, internal construction of things modelled> under the one metaphorical magical formula of "everything is an object" (for even it is, it is quite different on the six levels mentioned).

Here, by the way, is an example of the sort of logically confusing talk I have in mind, from the Guzdial book:

"Again, everything is an object in Smalltalk." (p.32) "Variables in Smalltalk are different from those in many other languages. Variables are not objects per se." (p.33)

O? The logical mind stands confused - and this on consecutive pages!

And here is an example from the same book of the sort of talk that seems to be the standard in Smalltalk introductions (I only suppress references to figures)

"We can create a box named Joe by asking Box to give us a new object. (..)
joe is an object.  joe is an instance of the class . joe knows that he is an instance of Box. If we ask him his class he will print it for us. Do a PrintIt on joe class printString (..)
Joe (we'll anthropormophize
[sic!] the object here) understands several messages . He knows how to turn himself a certain number of degrees. (..) He knows how to move himself a given number of pixels. " (p. 63)

To my mind, this type of metaphorical kiddie-talk - entities created by programmers in the innards of computers that are supposed to "know" (and "understand", "want" etc.) all manner of things, merely on the strength that they have code to do something - is plain categorical nonsense, and while metaphors are unavoidable in virtually any context, very much of the five introductions to Smalltalk I have read so far (by Visualworks, by IBM, the Smalltalk-80 Bible by Goldberger and Robson, and the present Guzdial text) is given to oodles of this sort of animistic "explanatory talk", that remind me much more of bad philosophy or theology than of a clear introduction to computing. Also, this is one of the rare occurences of this talk where it is at least minimally admitted that the language used IS in fact quite odd (anthropomorphic), and in actual fact quite silly.

Smalltalk IS a great language and a beautiful programming environment - that is marred and obscured by its animistic and metaphorical introductions, that make all manner of ludicrous claims when read literally, that moreover are wholly avoidable when one really knows what is meant, and that really obscure much of the point, beauty and elegance of the underlying code.

The problem of documentation is being attacked by Stéphane Ducasse. He works at the University of Berne (Switzerland) and collected a series of out of print books on Smalltalk that now have been converted to pdf and put on the web. Here is the link for downloading them:

http://www.iam.unibe.ch/~ducasse/WebPages/FreeBooks.html

This is very helpful indeed, and I will return to the books I have read when I have read them.

Note why this is helpful: I have access to the Dutch university library system, but it was hard to get Smalltalk texts. The ones I found and read where Smalltalk 80 by Goldberger and Robson (truly awful by my lights - and I am sorry, but such is the fact) and The Art and Science of Smalltalk by Simon Lewis that I liked. But others were not available, even if they once had been. Also, bookshops were no help, for apart from Smalltalk 80 every Smalltalk text was out of print.

Stéphane Ducasse has contacted the publishers and authors of out of print Smalltalk books and got their permission to convert them to pdf and put them on line. So there they are now, and I consider this a huge improvement, if only because I have been looking for decent documentation for more than a year.

Previous - Remarks - Next