More about documentation

Pablo (Kafka) pabloseb at ciudad.com.ar
Wed Jun 9 07:38:32 UTC 1999


Hi, Squeakers.

I'm quite a beginner with Smalltalk and Squeak. I was at once very impressed
at by the wonderfulness of these ambients; however, I must say that without
the help provided by a member of this list, Leandro Caniglia, may be I could
have been frustrated in my learning process because, among other things, the
lack of convenient documentation. This is specially true for the Morphic
interface, which, I see, plays an increasingly important role at the heart
of the Squeak project. So I think that documentation is *VERY* important,
not only for confused Wired readers, but for all kind of potential
squeakers.

But, what does the term "documentation" mean?

To many of us, it remind us of a bunch of explanations added to large,
confuse code. But it would be a mistake conclude that because Squeak code
isn't confuse (shouldn't be, in any case) documentation isn't necessary.
Moreover, I think we must redefine the very nature of documentation
according to the Squeak philosophy. This was pointed out along this thread,
but I think it wasn't remarked enough.

What am I talking about? Let's see:

1) We have BookMorphs. The power of BookMorphs for documentation purposes is
limited only by our imagination.
2) We have EventRecorders. They let us show a beginner how to accomplish a
given task  (e.g., working with halos). Show, not describe. There is no
better method of "documenting" the basic work within the Squeak ambient.
3) We have Swikis, SqueakPages, Squeak plugins, etc. So we can make
collaborative documentation work via the Internet while remaingin within the
Squeak spirit (or even within the Squeak system!).

Moreover, these examples show by themselves the power (and magic) of Squeak.

I'm not telling that method and class comments aren't important; they are.
But:

Object withAllSubclasses size       1942
Morph allSelectors size           635
(Object withAllSubclasses collect: [ :each | each selectors size]) sum
7278

My 2 cents,

Pablo.





More information about the Squeak-dev mailing list