[Zope] Keeping my promises - writing tutorials for Zope

complaw@hal-pc.org complaw@hal-pc.org
Fri, 26 Jul 2002 22:33:06 GMT

> What I would 
> like to hear from everyone else is, what things should be covered and 
> how, to which other resources and how-to's I should link to and -- the 
> most important part -- ' Hey nice idea, I could write about this thing' 
> or 'yes, I commented to the wiki just a couple of minutes ago'.

You are doing a wonderful thing.  I would like to make a few suggestions...

I've noticed that many people who start with Zope are coming familiar with basic
web concepts and, more importantly, are coming from work on other application
servers that, for whatever reasons, were not providing the functionality needed.
 Newbies need a context and a paradigm with which to work FIRST, before the
other things begin to make sense.  Aside from navigating (plus cut/copy/paste)
in the management screen, the first thing would be:

1.  Object Publishing (how to make an object appear on the web via a URL.

That seems elementary, and it is.  Moreover, there is some instant gratification
and the hope that they can do something useful (and are not wasting their time).

There is also a list of "common things" that people do on a web site that force
the site builder to add certain functionality.  Consequently, the newbie asks
basic questions like "How to I list objects on the site?"  How do I link to
objects within the site?  How do I list only _certain_ objects?" etc.  What they
want in those instances is a brief explanation and some sample code (sometimes
they just want the code).  Don't belabor the explanation.  Be brief and just
state how to do it.  You can always add a link to documentation that explains it
in full, if they are interested (most often, however, they won't be interested).
 The list of "how you do this and that" would form the bulk of your work, and
would be a huge help to the newbie community (and a reference to those who are
experienced but can't quite remember how to do it).

The next chapters would be _intermediate_ explanations on fundamental issues,
such as aquisition, security, etc. -- but in a way that adds only to the
practical functionality of web sites.  This is more in the line of "tips and
tricks" as opposed to detailed explanations.  Again, show functionality and only
_link_ to the detailed explanations.

The final chapters would be devoted to links to detailed documentation AND
provide the various options available in Zope for solving problems, such as
building things with ZClasses versus Products, CMF, etc.  In short, the last
section of the book is a road map of where to find other things in greater
detail, with an explanation of what potential those solutions offer.

That is what I would do.  (More importantly, that is what I always wanted when I
was a newbie.)

Good luck and best wishes,