I like stp's approach, since it removes the "clutter" of long stretches of source
code - if the documentation is really good, you shouldn't have to read the source to
figure out what something does and how to make it do it.  I would add the following:

1) Method documentation should include the method comments, the class of the
arguments for keyword messages, and the class of the object it returns (if not of
the same class as the receiver)
2) Selectors should link to the method source, formatted like Donia Bigalk's pages
3) I find it useful to somehow highlight methods which override those of the
superclass(es) - perhaps with a link up the chain?
4) If it is envisioned as a Swiki rather than a book, it can include
cross-references to pages of commentary, source code, other pages of the stp book,
examples, faqs, etc. added by community members or by the user in order to help
understand something tricky.

I know that it's easier to add two cents rather than actually do the work...
I'm just throwing out some ideas based loosely on how I learned what I know about
Smalltalk, mostly without the kind of documentation I wish I had.  Perhaps we should
collect these experiences we all have had - if we get some sense of how people learn
this complex system, perhaps we can do something constructive to help others along.

And yes, I'll help with the writing and editing.  I want to contribute something.

Ed