Started this reply on Thursday, just noticed that it wasn't sent...

On Thu, 13 Nov 2003 05:22:04 -0000, mwgrant2001 <mwgrant2001 at yahoo.com> 
wrote:

> --- In squeak at yahoogroups.com, "Lex Spoon" <lex at c...> wrote:
> ...
>> Go to the Swiki.  Look under "Documentation" and then "Morphic".
> You
>> will find a lot of tutorials and overviews about Morphic.  If these
> seem
>> lacking, and you can think of something specific that would help,
> then
>> by all means post your request either to the page or to this mailing
>> list.  Until then, however, I feel obliged to leave you with a
>> RTFM.  I ...
>
> Bad reply here. There ain't no FM--atleast to anyone who has had
> experience with 'real' manuals as opposed to code scraps slopped up
> onto a swiki. Of course you and other heavy contributors deserve a
> more respectful response than the preceding sentence. But the person
> asking the question deserves more respect too. (Wanting to get
> promoted to the 'R' mail help listings, huh? :o))

Hm, I can see both sides here.  I think I fall more on the "better docs 
are better" side, tho.  Back whenever it came out I bought a book called 
"Practical Smalltalk" (at least I think that was the title--I cannot find 
it on my bookshelf right now, but the one at 
http://www.iam.unibe.ch/~ducasse/WebPages/FreeBooks/PracticalSmalltalk/PracticalSmalltalk.pdf 
looks right) that I used to learn how to build applications in 
Smalltalk/V.  I think I've bought every book that Amazon has with Squeak 
or Smalltalk in the title, but I think what I want is just that same book 
updated for Squeak+Morphic rather than Smalltalk/V+MVC.

> Why not recognize the need by some individuals for a more formal,
> disciplined presentation of Squeak? This may particularly be the case
> for an experienced individual looking at Smalltalk for the first
> time. And, by VIRTUE OF THEIR EXPERIENCE they will want 'formal'
> documentation. If for no other reason, because every implementation
> of a language has its own idiosyncrasies ... particularly with
> respect to interface issues.

I would say that at some level I meet this description.  I would love to 
have "Formal" documentation, but I realize that the only practical way to 
get that is to hire a technical writer.  One thing I was thinking last 
week is that the "Worlds of Squeak" have lots of neat looking things in 
them, which might be handy building blocks for bigger applications.  The 
difficult I have is that for most of the interesting ones it is entirely 
unobvious (at least to me) how you'd go about reproducing them.

For a bare minimum of documentation to make me happy (realizing that as a 
defined goal, it is probably not very important to really anyone other 
than me) I think I would like a tutorial--or even just reproduction 
steps--for how to make your own "Worlds of Squeak".  Another tutorial (or 
even just write down the steps used) written by an experienced squeaker 
for how to go about writing something like a clone of the [file 
browser|system browser|squeakmap browser] with a little bit of the why the 
decisions were made at various steps would go a long way toward helping me 
particularly.

>> don't really understand why there are so many threads on the mailing
>> list saying we need more Morphic docs or more Squeak-intro docs.
> There
>> are tons of them.
>>
> Frankly, I've found spotty performance (bad links, code fragments)
> with what I have found online. However, I should log my journey and
> float that to the community. I also have gained some insights and
> good starting points for more substantive or composite examples. (My
> plan is to work on those, submit them, and then become defensive when
> their inadequacies are revealed!)

The message that I've found in all of the Morphic docs seems to be:  
Subclass some Morphic class and then...  The problem is that I'm never 
quite sure (1) which class to subclass, or (2) what happens next.

In Delphi, which I've been using a lot at work lately, if I want to 
present a new form to the user it is pretty easy.  I click the new form 
button and then add some widgets.  The system writes a subclass of TForm 
for me, and creates instances of the various widgets.  Superficially this 
seems similar to how Bob's UI works but after 4-5 hours of staring at it, 
using the minnow swiki and google, and poking at various things I was 
never able to get it to do anything other than stop working.

For those who have never seen it, the "Practical Smalltalk" book started 
with object design methodology, and then moved on to talk briefly about 
MVC.  The bulk of the book, however, was a set of case studies where the 
authors start with some simplified sample application, then take the 
reader through the decisions that led them to about the level of a 
functional prototype.

>> For larger examples, you can simply look around in the image.  For
>> example, the IRC client has a simple window with text fields when
> you
>> connect to a server.  When browsing the image, you will definitely
> want
>> to look into the gray halo handle, which has things like "inspect
> morph"
>> and "browse morph class"; these let you open up an example morph and
>> then disect it to see how it works.  Also, be sure to learn about
>> senders-of, implementors-of, inst-var-refs, etc. if you haven't
> already,
>> so that you can maneuver through the browsers effectively.
>>
>
> OK, now the above is good stuff!
>

It is helpful, but it is about like publishing a C library and providing 
no documentation because the source is included.  Sure, a really motivated 
persion will get over that hurdle, but unfortunately we are not all so 
interested in throwing effort away.

Also, there is (at least for me) a substantial disconnect between looking 
at a finished app and understanding the set of steps/decisions required to 
get there.

-- 
andrew_c_berg at yahoo.com