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: