[Zope] Docs

[Richard Moon]

Perhaps you should start with a non-technical description of what Zope 
does. i.e that it stores things in a database, things which can be web 
pages but can also be more clever than that, that at the time the web page 
is requested any dtml tags are interpreted/rendered (is that the right word 
?) to generate the final page. I think there's a tendency for newbies to 
think of DTML as a procedural language and forget what is actually 
happening. Try to avoid all the OO gobblydegook - it isn't necessary at 
this stage.

I think you need a really gentle introduction to namespaces/variables with 
lots of examples. Theres a need to explain the REQUEST variable ( a whole 
chapter IMHO) and how form variables get lost when you move to a new 
form,  information about passing variables to and from SQL methods, how to 
use the _. and all the functions such as _.string. All of this backed up by 
real-world examples (starting easy and getting more complex). Using 
variables within dtml-let and dtml-with tags. The focus should be on 'how 
do I do xyz' (eg how do I take user input, check it was entered properly, 
upshift it, concatenate it with a constant and insert it into a database) 
not what a particular tag does.

Can I say that the book I would most like you to emulate would be the HTML 
4.0 Sourcebook by Ian S Graham. No computer science, just what you really 
need to know.

Can I suggest that you make no assumptions about the previous languages the 
reader has.  Please don't assume they have Python or C or Java or Perl or 
anything. I would imagine you have to assume a basic grasp of HTML and web 
servers etc, and of course when you talk about SQL methods and Python 
methods you don't want to be teaching them those languages.

Good luck !

Richard


At 17:31 07/04/00 +0200, you wrote:
>Hi,
>
>I'm going to (try!) to write a small book on Zope. I hear people
>complaining a lot about the documentation with Zope. I'm all ears to hear
><snip>
>Regards, Tom.


Richard Moon
richard@dcs.co.uk