Hi Hannes,

On Mon, Apr 26, 2010 at 9:52 PM, Hannes Hirzel <hannes.hirzel at gmail.com> wrote:
> However for the vision part you brought up the idea of
>
>   "Squeak as the best documented Smalltalk system"
>
> I like this idea.

cool, thanks. :-)

> A friend of mine is a 70 year old mathematician who used to work for
> IBM 40 years ago. She says that she was taught at that documentation
> is 50% of the product. I think this still applies. ...

It certainly does!

> API documentation is fine but process oriented documentation is needed
> in addition.

Absolutely. I don't really know about others, but I usually learn much
better from tutorials, extrapolating usage patterns, than from sheer
API documentation. Recently, I learned how to use Java 7's
INVOKEDYNAMIC by reading the API documentation from alpha to omega.
That was interesting, but not much fun, I can tell you.

A much different but very interesting approach is the one Bruce Tate
takes in his upcoming book "Seven Languages in Seven Weeks" (Pragmatic
Programmers), in which he introduces (in the given order) Ruby, Io,
Prolog, Scala, Erlang, Clojure, and Haskell. Each language is briefly
introduced at a high level, and then there are examples. Lots of them,
and they very very quickly leave "Hello, world" style things behind,
introducing the really interesting bits of those languages without
getting overly complicated. (The Haskell chapter has not yet been
written, but the Clojure one has just been released in beta stage.)

Another great text is "Real World Haskell" by Bryan O'Sullivan, Don
Stewart, and John Goerzen. A wonderfully practical book on a
supposedly academic language. During the first few chapters, the
authors walk you through accessing the file system already, and some
chapters on, there is a complete bar code reader, from parsing the
input file (GIF, I think) over adjusting the layout of the code to
scanning the bars and emitting the code. *Cool*.

What I want to say is that such things are needed for Squeak. Not at
the same order of magnitude (I'm talking about books with several
hundreds of pages each), but in the same vein. I'm also not talking
about SBE - it's wonderful and important, but concentrates on the
tools more than on building mid-scale or larger-scale applications.

> Maybe we could have a goal of motivating 30 people contributing to
> documentation. Everyone writing a little tutorial and with a small
> sample application.

Or 15 people with 2 tutorials each, or 10 with 3, or whatever.

> A calculator, a game, puzzles, a scrapbook, a world clock, ToolBuilder
> examples, a small parser, some simulations, a little spreadsheet for
> doing a simple budget, a flash card came, a sound library browser, an
> outliner, the HelpSystem (with tags), a browser for flickr, a curl
> plugin example, example accessing this NON-relational databases (JSON
> based), a website done with Http view, links to Seaside more
> examples,.... you name it.

I could contribute a Z80 emulator. And probably a Smalltalk VM. ;-)

Best,

Michael