[smalltalk-central] Some thoughts about new tutorials

Mark D. Roberts mroberts at cincom.com
Tue Sep 26 23:23:26 BST 2006

At 12:51 AM 9/27/2006, Eric Winger wrote:
>Just a passing thought. I had envisioned that the tutorials would be 
>.pdf's or something like that, but maybe they can be just web pages. Then 
>the screen shots could be in a directory of images which could be screen 
>grabbed easily. Did you have any thoughts yet on what the tutorial format 
>would be?

My thought was to just use HTML. The images go in a separate directory, as 
you say, and then updates are fairly simple.

With PDF, of course you have to recreate the PDF every time you make 
changes to the non-PDF sources. We use PDFs for all documentation at Cincom 
and we are now moving towards both PDF and HTML. A lot of developers don't 
really care for PDF and the Adobe tools are getting clunky. To really do 
authoring with PDF, you end up needing Acrobat Pro, which is getting more 
and more bloated with each release.

With HTML, we'll need to settle on a few style sheet points, but it should 
be much more manageable.

Personally, I'm not so worried about maintenance of this content in the 
longer term. It's an editorial job and of course somebody has to do that, 
but it's a lot less work than getting the tutorial written in the first 
place. I'm more worried about finding people to write them.

Bruce had the following idea for an example:

>We could have a tutorial that built up the model objects for a photo 
>library (we all have heaps of digital photos these
>days).  We could then show how to build (code), populate, maintain and 
>query the model just using doit stuff - then
>people could move on to build, say, a web interface or a GUI or add in 
>real image manipulation stuff etc.  Then they
>could move on to persistence (Glorp, GemStone etc) ...

...which sounds good to me.

At the outset, the important thing is to have a good concept and a good 
example. If the tutorial is well-executed and the example is compelling, 
then somebody else can revise it to track changes in the IDE without much 
fuss. If the tutorial has too many problems, then the tendency will be to 
just dump it and start over from scratch.


More information about the smalltalk-central mailing list