[smalltalk-central] Some thoughts about new tutorials

Mark D. Roberts mroberts at cincom.com
Fri Sep 22 15:06:51 BST 2006

At 01:40 PM 9/22/2006, Eric Winger wrote:

>Le Sep 21, 2006, à 7:22 PM, Mark D. Roberts a écrit :
>>First, as I've been building up the current tutorials page, my sense is 
>>that about 95% of the stuff currently available on the web is unusable. 
>>There's a lot of out-of-date, poorly-written and amateurish junk that 
>>should eventually be yanked from the net. We can't do that, of course, 
>>but we can avoid linking to stuff that we know is unusable.
>Agreed. Buuuutttt. What consitutes unusable. As i started perusing 
>tutorials, I realized I'm not sure what is and what isn't usable. Shall we 
>set up some guidelines to go on?

OK, here are my thoughts about criteria, in free form...

For any new tutorials, I'd like to see the following:

(1) The tutorial should offer a "complete" experience, from introduction to 
conclusion. If the tutorial contains several sections, each should produce 
a sense of having reached some goal. It is not necessary, though, to 
mechanically state goals at the beginning and recap them at the end.

(2) The writing should be clear, concise and engaging. The grammar must be 
as perfect as possible. This can be accomplished through a review process.

(3) Instructions concerning menu picks and code examples must be completely 
up to date. Any example code should be easy to load into the IDE. The user 
should not have to guess, improvise, fiddle, or do a web search to try and 
interpolate the "correct" information for the Smalltalk IDE because the 
tutorial is out of date or otherwise out of sync with the IDE.

(4) Screen shots should be consistent, attractive, and current. There are 
various tricks to avoid capturing that butt-ugly Windows XP look, and we 
should try to use them.

(5) At the outset, the tutorial should state its intended audience and it 
should remain "on message" throughout. It may be written for unvarnished 
noobs, those with no prior experience as developers, or it may be written 
for developers who have no familiarity with objects, or for Java/C++ 
developers who have "other" ideas about objects, or for developers who have 
started with Smalltalk but want to deepen their understanding, or it may be 
for existing, knowledgeable Smalltalkers who want to learn about some new 
framework or subsystem. Whatever the case, the intended audience should be 
stated explicitly and understood implicitly by the author.

Do these sound OK? Any other requirements?

Next, most tutorials seem to include a couple of "typical" discussions. 
There's the "here's how to get the IDE installed and running" discussion, 
the "Smalltalk has a venerable history involving Alan Kay, Xerox PARC, 
etc." story, and the "Smalltalk syntax is actually cool and it works like 
this" discussion, the conceptual discussion of a few basic OO concepts, the 
short tour of the system browser, and finally, the steps to actually do 
something (explore a class, create a class, build a UI, etc.).

My thought for the Smalltalk-Central tutorials is that we would separate 
the instructions on getting the IDE installed and running. Those would be 
dialect-specific and a tutorial can presuppose that the IDE is installed 
and functional. We can also separate the discussion of Smalltalk's history. 
A tutorial for noobs should include some of this, but we could have some 
separate, longer articles that address the history of the language. 
Parenthetically, I would really like to host a nicely-formatted version of 
Kay's "Early History of Smalltalk" with high-quality scans of the original 
images that he used. The discussion of Smalltalk syntax should be 
hyperlinked to a separate "language reference" that is more comprehensive. 
This could also be used in the FAQ. We need an up-to-date and thorough 
discussion of the syntax and semantics of the language, covering things 
like name spaces and pragmas. The discussion of OO concepts could be 
elaborated in separate articles as well. There are a lot of arguments about 
these ideas and their implementation in various languages.

The introductory parts of a tutorial, and the sections of interest to noobs 
and historians do not need to be tied to any particular IDE, but everything 
else involving tools or advanced APIs for web apps, databases, services, 
etc. will need to be written for specific dialects. This is unfortunate, 
but it's the reality for now.

We might also cross-link from tutorials to screencasts, so that its 
possible to see somebody else driving the IDE and performing steps in that way.

Finally, I think it's important to distinguish tutorials from documentation 
and walk-throughs. Documentation has a different structure and spends more 
time on concepts and comprehensive coverage of subsystems. Tutorials are 
shorter, more focused on specific goals. Walk-throughs are also very 
goal-oriented, but more conversational, less comprehensive.

Those are my thoughts for the moment. Feel free to dispute any of these 
points or suggest others.

I'd like to assemble a task list so that we can divide up the work into 
manageable pieces and try to find others who might interested in contributing.



More information about the smalltalk-central mailing list