Hello Tim,

Timothy Rowledge wrote

> On Feb 18, 2004, at 3:04 PM, Maarten Maartensz wrote:

> > Hello,
> >
> > Lex Spoon wrote:
> >
> >> Neato!!  What a piece of work!
> >
> >> How about putting a link on the Swiki somewhere, under "Introductions
> >> to
> >> Squeak" perhaps?
> >
> >> -Lex
> >
> > Thank you.
> >
> > Actually, I am no fan of the Swiki. It may have its uses, but it is
> > not good as
> > documentation or as introduction to Squeak for newbies

> Note that Lex suggested putting a _link_ to your work on the swiki, not
> the work itself. At least that way you get to improve the lot of
> anyone, like yourself, trying to find help via the swiki. It's a win
> for everyone!

Yes, you're right of course. But my underlying point was this: In my experience,
and in the experience of Richard O'Keefe I quoted, and no doubt in the
experience of many others who were just lost (temporally or for ever) after
trying hard, the Swiki - what's the fashionable lingo? Ah yes: it - sucks. It is
a mighty morassy maze of random bits by random authors with random competence
and insight written at random times about random Squeak-versions.

Now if there were nothing better, alas and so it be. But I think the way I
started is a better way. Even so, the lot could be on the Swiki as well, zipped
or not, except that I don't think it a good idea to proceed then in a Swiki-way
of "improving" it - say years of unmoderated random accretions as summarized in
the previous paragraph. (My general underlying point is: Nothing good ever has
come from a committee, possibly apart from the King James translation - and I'm
speaking of the prose, not the religion. And if
these fine translators had used a Swiki, per impossibile, I fear the translation
would be still in the making and "ready RSN".)

> Just taking a very quick look at your help stuff it becomes very plain
> that
> a) you've worked hard on this for which we should all thank you
> b) some of it can be improved with help from some of us with more
> experience and we should offer that help
> c) some things are hard to explain and should be simplified. My general
> attitude is that if it is hard to explain it's probably wrong.

Yes, I think you are quite right on all three counts. And my own addition
(speaking from my experience: a non-Smalltalker without a CS-degree, who happens
to believe Squeak is the best thing he saw in 18 years of daily computing)  to
your c) is: What makes Smalltalk and Squeak harder to comprehend than necessary
are

(1) the animistic language of many of the introducory explanations
(2) the lack of (up to date) documentation
(3) the Swiki, so fondly recommended by many, so disheartening in practice

As to your point b): Indeed, that's the attitude! And you would be the one I
would - eventually, since it is a deep subject - ask to write the explanation of
the VM (which you have done in part e.g. in the pdf in the
'many-authors-on-Squeak-book').

> As an example for c) I'd point out my swiki doc for the VMMaker. In
> writing that I found at least half a dozen changes I needed to make to
> the code so that it worked in a way that was possible to explain. If
> you can't explain it, nobody will use it. If nobody uses it, why did
> you write it? This is the basis of the "Goldberg Doctrine" - "if it
> isn't documented, it doesn't exist". In a commercial setting one should
> expand this to "... and if it doesn't exist, why exactly did we pay
> you?"

I couldn't agree more, except for the riders you added: Of course there may be
personal satisfaction and personal use in code that is not documented. Apart
from that: The notions

(I) If  you can't explain it, nobody will use it.
(II) "if it  isn't documented, it doesn't exist".

seem to me quite sensible and largely correct (and according to 'literate
programming').

But if so, then - "strictly speaking", as the appropriate lingo here is -  a
very great part of Squeak is NOT used by anyone and does NOT exist. And indeed,
if you compare the quote of Dan Ingalls I give in Squeak Help, or the Principle
of Mastery I quote from Dan's 1981-Byte article, there is MUCH to do to prevent
Squeak's many beauties and great potential disappearing in the morass of
undocumented not properly readable code, that only exists for a handful of
enthousiastic techies with many years of experience and application.

Regards,

Maarten.

P.S. Perhaps I should say that I am on the DIGEST of the developers-list: I get
twice or thrice daily all mails collected, instead of a continuous trickle over
the day. For me that is more pleasant, but it means I usually will not answer as
fast as others.