What i note from your excellent point of view is:
- in the image, we are like god (and we like it i guess)
- a good tutorial should teach us that breaking an image is not the end of the world, we can recover from that. (I am also still afraid maybe because in early Smalltalk/V, it was not that easy).
- we all need a good step by step tutorial (Dan, i guess you had not access to the Smalltalk/V tutorial, because your basic example would have been much easier with this excellent book)
- all the time we spend inspecting the wires down to the power plant when we just have to install a bulb is the Smalltalk way of building the house. An investment well retributed by future economy of coding... This way, we not only reuse our own code, we reuse code from the whole system.
Smalltalk syntax is rather readable, and code is so easy to be changed. So, i still think the best detailed documentation of code is the code itself. But i think we lazily rely on that property, and do not write enough documentation. We rely too much on browsing (i speak for myself). This is not practicle in modern oceans of code.
As complexity is growing, proper organization (Monticello packages, traits, something higher ?) and documentation (implementation guidelines and short tutorials) is a key to Smalltalk success. And this is valuable not only for newcomers. Ideally, this documentation would be accessible from the image. I do not know at which level it should be attached (package ?), and under which format, but web like navigation sounds good to me, with crossrefs and links. The documentation found in squeak projects is something i like. Should SqueakMap have such projects attached ? Would it be possible to navigate through such worlds located anywhere on the web ? We have to invent the tools... (is this Croquet ?)
Nicolas