[REQUEST] updated documentation

Alan Kay Alan.Kay at disney.com
Sun Nov 21 01:37:21 UTC 1999


Hi Stefan --

As Dan mentioned at OOPSLA, a few months from now we will release an
experiemental net-based version of Squeak that will have many concrete
examples for people on the Squeak list to play with. One of the reasons we
haven't tried harder to make many of these facilities easier to understand
is that there are only 7 of us at Squeak Central, and the majority of the
code has been done by just 5 people. We have felt that a premature release
of something that looks like it is for endusers could very well bury us
with questions, complaints, etc. This is why we have pointed the Squeak
list towards expert Smalltalkers.
     With the upcoming net release, there will be lots of "questions,
complaints, etc.", but we will be more in the mood for such things, having
tied up as many loose ends as we can up to the release date. This will
still be very experimental, but part of the experiment will test how
understandable are certain parts of the system....
     We look forward to your reactions and comments.

Cheers,

Alan

---------

At 5:00 PM -0800 11/20/99, Stefan Rieken wrote:
>Hi,
>
>I just answered a question on comp.lang.smalltalk about some Squeak
>specific documentation. I found that I could only give him a few old
>links.
>
>Although old links don't need to be obsolete, AND although Squeak is
>experimental, this made me realise that the current documentation is not
>really representing the current system. A few examples:
>
>- This "Scripting" thing. Never got quite used to it. I recently came
>upon something called a "Scripting Area" and I had no idea how to use
>it. I found one document on minnow's SqueakDoc, a quick introduction
>that belonged to version 2.2. The tutorial on Morphic has only got a
>part one, while the other parts ("PicoPaint") never seem to have
>arrived.
>
>- Let's say I want to do Flash. VRML. Import a truetype font. It is all
>possible, the only thing I miss is the knowledge, or a nice example.
>
>- Minnow's SqueakDoc documentation still announces 2.4. Although our
>versioning goes fast, this looks a little outdated to the user.
>
>An average human is a hard learning machine and needs thourough
>documentation in order to get to understand things. (The "RTFM" effect.)
>I think that the current Squeak documentation reveals only the tip of
>the iceberg to the user, and therefore doesn't do the current Squeak
>really justice. Only the code wizards can now play with the full system;
>the "end users" need to dig too much information in order to get a
>simple beginning with some (if not all) of the Squeak subsystems.
>
>(more or less) Thouroughly documenting the options that make Squeak
>powerful and different form other smalltalks would really help. I also
>think that it is possible when I see the average development rate of
>Squeak.
>
>Greets,
>
>Stefan
>
>(Our "Do It Yourself" community tells us to try and make it yourself
>before asking for something. I do however not have the write access to
>SqueakDoc, and, more important, I would still be on the "client" side of
>this documentation - I am not a code wizard myself.)





More information about the Squeak-dev mailing list