Squeak Help 02

Timothy Rowledge tim at sumeru.stanford.edu
Thu Feb 19 00:37:46 UTC 2004


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!

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.

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?"


tim




More information about the Squeak-dev mailing list