>From: Ramon Leon <ramonleon at cox.net>
>Reply-To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>To: The general-purpose Squeak developers 
>list<squeak-dev at lists.squeakfoundation.org>
>Subject: Re: Thoughts from an outsider
>Date: Mon, 04 Sep 2006 19:40:15 -0700
>
>That you are attacking anything, is what bothered me.  You've used strong 
>insulting language from the start, not against me personally, I take none 
>of this personally, but against the self documenting style. You may not 
>prefer this style, but many do, as we've developed a mistrust of documents 
>not directly linked to code.
>

This cancerous, destructive idea of "self documenting code" is a big barrior 
to people
new to the language, and I would be willing to bet that is the main reason 
it isn't taking
off faster.

I can tell you I have done various projects in various languages to get a 
feel for it, and
never before have I felt like I could do so much so fast, and yet not been 
able to do
very much at all.  Why?  Because the state of documentation right now is 
almost
impenetrable.  Anything I do, I feel like it is probably already there in 
some system
that I don't know about and have no way to find out about.

The main documentation right now, as far as I can tell, seems to be the 
mailing list.

"self documenting code" as a source of documentation is simply not valid.  I 
am pretty
surprised that such an obvious statement has so much resistance.

If source code is the documentation then the bar for becomming productive in 
the
language is the amount of time it takes you to absorb the entire Smalltalk 
class heirarchy
from the browser.  And if you download a new system, then you have to read 
through
every line of source code from that system.  And that isn't enough, simply 
reading the
code isn't enough.  You have to wrap your brain around *why* it does what it 
does.
Otherwise any change you do is probably not going to be helpful.

As an example, I downloaded 3.8 from the web site and started trying to run 
a cool 3d
example I saw on one of the tutorials.  Everything worked fine until I tried 
to bring up
a viewer for my fish so I can make it move and stuff.  It brought up a 
debugger because
the "costume" message wasn't understood.

I took your advice and went all around trying to understand the code.  In 
the end it looks
like maybe the "WonderlandActor" class might have been a subclass of Morph 
at some point
and isn't anymore.  Maybe it changed to a composite patern.  So I tried to 
see if there was
a reference to something I could forward the message too.  But I didn't see 
any morph's in
his instance variables, so at this point what?

All I can do is post a message on a mailing list.  I don't know who changed 
what or why, I don't
know how it was suppost to work and I have no clue where I would look for 
some kind of
documentation.

I spent at least an hour tracking through this and came up empty handed.  
That is bad
enough for playing around, but in business that would mean not using what 
ever
component it was and writing our own from scratch.  And if we have to write 
everything
from scrath then we are not getting the efficiencey from the language.

>You place great value on documents, OK, great, but not everyone does, no 
>need to use such strong language.  You can approach the subject of more 
>documentation without being insulting to those who disagree with you. 
>Rather than arguing "for" documentation, you seem to be arguing "against" 
>less documentation, rather like a creationist arguing "against" evolution 
>rather than "for" creationism.
>

The arguments "for" documentation are obvious and I (and others) have stated 
them.

Smalltalk has some good momentum right now because of what various folks 
have done with
Seaside and the subsystems based on it (Pier and co.).  But momentum doesn't 
mean anything
unless you can sucessfully turn it into something else before you lose it.

All the other languages will steal everything you have.  Anything good, 
revolutionary, etc. will
be recreated in those languages and then they don't feel the need for 
smalltalk anymore.  It
happened with Steve Jobs in the beginning, it happened with Java when it 
started and it will
happen with Seaside eventually.

And I am not just throwing out insults, I intend to help fix the problem.  
But first the problem
must be identified and acknoledged (no one will work to fix something they 
feel is not broken),
then possible solutions have to be explored.