Another Morphic Tutorial

Richard A. O'Keefe ok at atlas.otago.ac.nz
Thu Apr 19 03:04:06 UTC 2001


Dan Shafer <dshafer at yahoo.com> asked:

	How important is it, Alan, for those of us writing tutorials and other docs to
	use this same terminology, in your view? I mean, is this really important stuff
	that has a lot of thought behind it that we shouldn't disturb or should we feel
	free to re-think it?
	
Can I answer this from the perspective of someone who needs to *read*
the tutorials, and couldn't possibly write them (yet)?

When I use Squeak, I seem to spend a *lot* of time browsing around the
system, using Cmd-f in a browser or bringing up a method finder or whatever.

Suppose for argument's sake that someone decided that
	halo => necklace
	handle => bead
would be a better set of names.  Come to think of it, I rather like them.

Next a student works with a tutorial for a bit, and then starts to wonder how
it all works and what they can steal.  (Smalltalk is *supposed* to be like
that!)  So they bring up a method finder and look for "necklace".
'necklace' leads to nothing
'bead'     leads to maybeAddCollapseItemTo:

When the student *does* eventually stumble on 'halo', they're going to
have to keep *two* sets of names in their heads, the names used in the
tutorials and the names actually used in the system they are exploring.

Writing a tutorial for Squeak is different from writing a tutorial for
Microsoft Word, because it is legal, moral, and entirely non-fattening
to look at the code.  Every technical term has to serve *two* purposes
in a tutorial:  helping people to understand the concept, and helping
them to find the code and use it.





More information about the Squeak-dev mailing list