Am 16.01.2006 um 10:00 schrieb Marcus Denker:

> On 16.01.2006, at 09:21, Cees De Groot wrote:
>
>> On 1/16/06, joshscholar at nightstudies.net  
>> <joshscholar at nightstudies.net> wrote:
>>> Documentation, and it's lack is one of my pet peeves from my  
>>> working life,
>>> so forgive me my passion on this subject.  But perhaps I can say  
>>> something
>>> useful.
>>>
>> Yup, but please don't cut trees for it. Documentation in bookform
>> (even electronic, like PDF) is all but unusable in Smalltalk.
>
> I disagree. Of course, once you know how to use Squeak, you don't need
> a book. But a book woukd be crucial if the goal is to make it easy for
> new people to learn it.
>
> First problem: People who want to discover Squeak won't *believe*
> that a book is not needed. Don't even try. If the goal is to make  
> Squeak easy
> to learn, write a book. Kind of like an API to implement. Leran ==  
> Book. No book,
> no learn.
>
> Another thing is that a book should tell you the stuff that is not  
> trivially apparent,
> like how to use Squeak to find more infos so you don't need that  
> book ;-)
>
> It should talk about Design, Patterns, good style, good ideas (e.g.  
> testing), stuff
> like that. You can't tell me that this is "apparent" from just  
> looking at Squeak
> (especially as Squeak is mostly an example of what *not* to do!)
>
> And trees: That's what it is, even today. I print every paper I  
> have to read,
> I don't know many people who read pdfs on screen.
>
> I don't think that a language can be successfull without having
> "the book" published. E.g. Ruby's success ouside japan is
>  unthinkable without the book.

+1

However, for such a book you need a great author, particularly for  
the Good Style part, which should not be a separate part but mention  
it in passing. I'm a bit sceptic the community could create such a  
thing, I rather think some individual would have to take this on.  
There have been people on this list with a great writing style, but  
it's a major undertaking none-the-less.

Something that would be possible for the community might be updating  
the Orange Book for Squeak. That would be particularly helpful to  
newbies, learning the Smalltalk way of interactive development,  
rather than the edit-save-compile-run-crash-cycle they're usually  
used to. This is the basic thing you cannot learn from looking at  
source code.

Instead of dead-tree class documentation I'd rather have a filtering  
System Browser which shows only selected classes and methods, based  
on a community effort to properly categorize methods.

- Bert -