[smalltalk-central] Some thoughts about new tutorials

Eric Winger eric at thewingers.net
Tue Sep 26 05:09:10 BST 2006

I generally agree with the principals here. Expanding on your task list 
comment at the end, I think we should create a list of desired 
tutorials, assemble them, then discard everything else on the tutorial 
dump page. Then, after finishing the initial list, we can add tutorials 
in the same format for specific topics.

I started to make a list of tutorials, then I got bogged down thinking 
about how to do this. The biggest problem is, what to do about the 
flavor specificness of each smalltalk. Do we have the same tutorial 
basically rewritten for each tutorial in the same format?

The other big thing I see is how do we maintain these. I don't want to 
see them get out of date as soon as they are written, because screen 
shots suddenly go out of date. Ideas?

This gets harder the more I think about it. Maybe I'm just tired 

On Sep 22, 2006, at 7:06 AM, Mark D. Roberts wrote:

> 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.
> Cheers,
> M
> _______________________________________________
> smalltalk-central mailing list
> smalltalk-central at lists.openskills.org
> http://lists.openskills.org/cgi-bin/mailman/listinfo/smalltalk-central

More information about the smalltalk-central mailing list