I won't say documentation isn't needed, but I think you are missing the 
point.  It isn't that smalltalk code is easy to read (though some may 
argue it is), it's that smalltalk code is easier to *navigate*. Senders, 
implementers, references; these things make it easier than in any other 
system I've used to find your way around quickly.  Not to mention the 
method finder.  If more of our code had good tests, a simple senders 
check would give you a very good idea of how to use the method and of 
whether it is public/private/etc.  A few choice class comments to give 
slightly broader information and we'd be in good shape.

Overview information is still great to have as well but we're talking 
pretty broad here and I'd say at the level that could easily be handled 
on a wiki.

I won't deny that many newcomers crave more printed documentation and 
part of that is because they're new and need more documentation, but 
another part of it is that they're new and can't picture a world where 
you don't need the documentation (I can't even fathom working with, say, 
MFC classes without printed docs).  So "read the code" is not just a cop 
out; it's partly based on the experience of seeing a lot of new people 
come onto the list with the same concerns and most of them catching on 
pretty quick and becoming as productive in Squeak as the rest of us.

You have to remember that resources are limited and most of us would 
rather spend a few minutes pointing newcomers to the tools (teaching 
them how to fish, if you will) rather than spending a year writing a 
book that will be incomplete and out of date a year down the road.

Like I said, I won't say documentation is a bad idea; I'd love to do it 
myself, in theory.  But there just doesn't seem to be anyone, currently, 
for whom having the largest possible number of squeak users is a big 
enough priority.  And until there is, most people will prefer to spend 
their time just being 10x more productive in their language of choice.

Oh, and I learned more of Squeak faster without docs than I did 
Borland's OWL library with about a half-dozen books (and I think OWL was 
*easier* than MFC :) ).

Julian

joshscholar at nightstudies.net wrote:
> I agree that there's no substitute for documentation written by humans for
> humans.  It's good that smalltalk code is easier to read than other code,
> but even the best code only gives you local information (unless you read
> every line in the damn system, inspect every varible, trace every routine) -
> you need overview information too.  And that needs to be organized and
> complete.  "Read the code" is a cop out that ignores that fact.
> 
> Josh Scholar
> 
> ----- Original Message ----- 
> From: "Lynn Hales" <lhales at earthlink.net>
> To: "The general-purpose Squeak developers list"
> <squeak-dev at lists.squeakfoundation.org>
> Sent: Monday, January 16, 2006 10:25 AM
> Subject: Re[2]: Good, thorough Smalltalk reference
> 
> 
> 
>>Hello Gary and All, for me documentation is paramount.  By looking at how
> 
> many Smalltalk programmers there are and how many "newbies" there seem to be
> there is a large barrier to entry that I think many can't or don't want to
> see.  It's documentation, how to's, cook books, best practices all in book
> form - electronic or paper. Class comments are very important but they are
> not even close to a substitute.  Up to date writings are mandatory for wider
> adoption and participation.  All the talk about learning the class library,
> how to program in Smalltalk, how to create GUI's in Morphic by reading Class
> comments is nuts.  That's not a best practices approach and by just looking
> around it is easy to see it isn't working.
> 
>>If we want the benefits of wider participation in the Squeak world then we
> 
> need to write and keep what has been written up to date.  Lynn
> 
>>Monday, January 16, 2006, 4:22:29 AM, you wrote:
> 
> 
>