Hi Richard --

Well, I agree with pretty much everything you've said here -- this is 
why I don't complain about lack of adoption of these ideas -- if we 
don't document them so that others can use them, then we shouldn't be 
surprised at the rise of frustrations such as you describe. This has 
been a big problem even with the etoys which we have tried to 
document to some extent for http://www.squeakland.org.

I know you do appreciate that our Squeak work at Disney was a 
headlong rush of a small group to get a lot of things done and 
demoable to our sponsors. So we didn't have extra cycles to do 
documentation. Since Disney, we've been scratching along with our 
nonprofit Viewpoints Research Institute with a very reduced 
sponsorship, and we decided to take on a new research project to 
boot, which resulted in Croquet. This does have some documentation 
thanks to David A. Smith.

I've been trying to figure out a practical way to capture a lot of 
the "here's how you do x" in a form that others can use to make real 
documentation.
      I've recently been really inspired by the Japanese response to 
the etoys stuff (and to new ideas in general). They have gotten very 
enthusiastic about the etoy approach and are starting to put it into 
schools in Japan. What they do is to attend talks that we give and 
use them as the basis for a really detailed summary of the ideas put 
forth. One example that really overwhelmed us is a website, mostly 
about the etoys stuff, done by Yamamoto-san (whom we haven't yet met) 
that has literally hundreds of webpages of documentation in Japanese 
and screen shots showing how to use etoys. This is so good and so 
extensive that we are in the process of translating the site to 
English in order to get this documentation!

The expansion of etoys has also led to a need for more project ideas 
at the Junior High and High School levels. And, as usual, we don't 
seem to have the time and energy to sit down and do the writing and 
layout that is needed.

So my thought is to try to imitate the Japanese process by doing 
demos, capturing them and distributing the rough video and 
transcripts on CDR's in the hope that someone who likes to document 
and is good at it (like Yamamoto-san) will take the content to a more 
usable level. I will start doing that in March and will encourage 
other Squeakers to do the same. Maybe this will help.

Now to Geemails. This was one of several nifty projects that Bob 
Arning did with us. Ironically, this was a documentation idea -- 
originally for explaining ideas through Squeak emails (hence the 
name).
      The idea is to make a scrolling galley object that can do both 
text and "do the right thing" with embedded objects. The usual way I 
use it is to have the Geemail object be twice as wide or so as the 
interior text object. Then I start writing some explanation (say) to 
one of our teachers. As I write my way down the galley, I can put 
other objects, including working objects, either in the text (by 
dropping) or in the right margin (by dropping). Bob has it set up so 
that drops acquire anchors in the text so they will stay where they 
should stay even if modifications to the text are made upstream.
      Scott Wallace made an object that is a little etoy world called 
"Scripting" (found in the Widgits flap) that is a little namespace 
environment so you can show sequences of etoys.
     Bob shows where the page breaks will be if you print, and there 
are options in the Geemails menu (above the scroll bar) to force the 
galley into columns, etc.)

This didn't get done all the way because of the exit from Disney, but 
I still think it's a good idea to have a way to provide multimedia 
Squeak explanations via email -- I would be using it now to 
demonstrate itself, for example.

I've enclosed this email as a Squeak project showing the Geemail and 
also put it on BobsSuperSwiki.

Cheers,

Alan



The question is whAt 2:24 PM +1300 2/13/03, Richard A. O'Keefe wrote:
>Diego Gomez Deck <squeak-dev at lists.squeakfoundation.org> wrote:
>	These goals are, imho, incompatible between them.  If we want to
>	see the next shift, let's forget about compatibility, stability,
>	documentacion, etc.  On the other side, if we want to see a
>	"solid" smalltalk to create "standard" business applications,
>	let's forget about eToys, Croquet, etc.
>
>I don't think it's a pink-plane vs blue-plane thing at all.
>To pervert the metaphor, it doesn't matter what colour the
>plane is IF YOU CAN'T BOARD IT.
>
>If I've understood Andreas Raab correctly, he is firmly of the
>opinion that EToys is not a rival to a solid framework for building
>business applications but, amongst other things, a first draft of
>just such a framework, that if you want to build a standard business
>application, EToys should be a much faster way to do it.
>
>The way I see it, it's an insider vs outsider thing.
>
>If you are a Morphic/EToys insider, then you *can* do amazing things
>and you *can* build business applications that might not be "standard"
>(unless you really want them to), but *would* be usable and a pleasure
>to use, and you think it's all plain sailing and fun doing so.
>
>If you are a Morphic/EToys outsider (and yes, I've read the Squeak books,
>I've read the original Morphic paper, I've even got Self on my machine,
>and I've read lots of Morphic tutorials) then you are awed by the amount
>of really cool powerful stuff there and frustrated and depressed by the
>difficulty of finding out almost anything about how to USE it.
>
>I am still puzzled about what GeeMail thingies are all about; they seem
>to have nothing to do with mail, g forces, or the gee-gees.  I'm not even
>precisely sure what a "playfield" is.  Look at the class comment for
>GeeMailMorph:
>
>	Well, what can I say?
>
>Not a good start for programmer documentation.
>
>	GeeMail is a scrolling playfield with a text morph
>	(typically on the left) and room on the right for other morphs
>	to be placed.
>
>GREAT!  Except, of course, that if you were looking for such a thing,
>you would never dream that it might be called GeeMail.  You'd go looking
>for ScrollingPlayfield.
>
>	The morphs on the right can be linked to text selections on
>	the left so that they remain positioned beside the pertinent
>	text as the text is reflowed.
>
>Yes, but HOW?
>
>	Probably the best thing is an example and Alan will be making some
>	available soon.
>
>Yes, an example would be good, but an example of what one looks like when
>it is finished doesn't show you how to *construct* one from the UI or
>how to drive it from code.  Nor does a promise that there will be some
>examples "soon" (presumably written some years ago; I'm looking at a 3.2
>system which is what our 3rd year students will see this year) help me to
>find examples _now_.
>
>While the GeeMailMorph class comment is only _just_ helpful, it is also
>the only class in the Morphic-GeeMail category with _any_ useful class
>comment (the one other class that has a class comment basically says
>not to use it).
>
>The standard retort to people who need to find something out (I've used
>it myself) is "you have the code and a great IDE, go look".  But in the
>Morphic-GeeMail category, there is only one class whose methods are not
>all lumped into 'as yet unclassified', and that is GeeMailMorph itself,
>which has no methods.  Poking around in this lot trying to figure out
>_how_ you can connect a morph to some text is MUCH harder than it really
>needs to be.
>
>Oh, and don't tell me "go search the Swiki".  Today I can't go off-campus.
>Mail's being queued, but as for using a browser to search for stuff, NO
>CAN DO.  What use is documentation (if it exists at all) you can't get to
>when you need it?  (So that I can have a life, my home Mac isn't on the
>net at all, which makes Swiki documentation permanently inaccessible,
>instead of intermittently inaccessible.)
>
>*THIS* is the single biggest problem with Morphic and EToys: the steep
>learning curve brought about by the truly dreadful state of documentation.
>
>	I have not a clear position on it but if I'm force to choose
>	I'll choose to work in the next paradigm shift.
>
>If the next paradigm shift isn't any better documented than the last
>one (Morphic, EToys) was, then BUGGER it.
>
>I almost never swear.  I believe this is the first time I've ever used
>a swear-word in e-mail.  But here I am, an enthusiastic Smalltalker, a
>technophile, keen to play with things and to learn new ways to do things,
>and very admiring of Morphic results that I have seen.  And I am just so
>FRUSTRATED.
>
>If only there was something like Brent Welch's Tcl/Tk book for Squeak,
>*assuming* a basic knowledge of Smalltalk syntax and Collection classes,
>explaining Morphic, EToys, Tiles...  A good How-To book with *all* the
>information you need, right there in one place.  Something you can
>actually get up to speed with, without having a veteran insider as your
>teacher.
>
>Someone commented recently that constructing a Morph via the UI was no
>use if they couldn't recreate it at will.  Well, control-click on the
>title bar of a system window, and you'll see "save morph in file" as
>one of the options.  Once the morph is saved, you can bring up a file
>list, find the file, select it, option-click, and the top option is
>"load as morph".  Amazing stuff.   Being able to save an open Browser
>in a file and later on bring it back!  Awesome.  But it requires
>persistence in digging and a willingness to put your image in what
>_feels_ like extreme hazard to find some of these things.
>
>Of course, if you try this with the "Worlds of Squeak" window, you
>get a saved moprh, but the project it points to isn't there any more.
>This is not the kind of thing that encourages exploration.


-- 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Richards_Geemail_Example.001.pr
Type: application/mac-binhex40
Size: 126293 bytes
Desc: not available
Url : http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20030213/2d834508/Richards_Geemail_Example.001.hqx