[Zope] Forking the Mailing List

[Lee Hunter]

>Brian Hickman writes:
>  > My proposal is that DC builds or blesses a detailed topic map re. 
>knowledge
>  > of Zope (Installation, RDMS, DTML, Security, the various products, 
>etc.) on
>  > Zope.org, and invites members to contribute to filling in the topic map 
>with
>  > questions, answers, example code, etc.  A FAQ + a topic map.  ZDP

I'm a technical editor at a mid-size software company and so I might be able 
to speak to the question of Zope documentation. To me, what seems to be 
desparately lacking is a real user guide. By that, I mean a highly 
structured manual that is entirely focused on accomplishing common tasks and 
procedures, rather than on Zope concepts and API.

This is not a criticism of what is available now - the more conceptual 
material - the Zope Book and Dieter's book - are excellent resources and 
required reading for anyone who wants to 'get' Zope. But (in an ideal world) 
there should also be a very structured set of step-by-step procedures for 
all of the basic tasks involved in putting together a typical site.

Much of that material is there already in the HowTos but to an editor's eye 
the HowTos (taken as a group) are an overwhelming and utterly disorganized 
jumble.

To do a proper user guide you would have to start from scratch and begin by 
working out a table of contents.

In the table of contents the chapters, sections, and topic headings would 
not contain any references to Zope jargon (ZClasses, DTML, ZPT etc) but 
rather, they should be rigorously pruned down to simple objectives ("Index a 
Website", "Add a Navigation Bar", "Process a Form", "Connect to a SQL 
database" etc.).

Once you have a relatively complete TOC (although obviously you can't cover 
everything) you can look at the existing sources - the HowTos, the Zope 
Book, list archives etc -  and see what available material would cover the 
topics in the outline. To do it properly, most of the HowTos would need a 
great deal of pruning to get some kind of consistency, to remove the 
conceptual stuff (which is useful but not in this context) and to reduce 
them to a series of simple steps (a maximum of about ten steps per 
procedure).

The end result would be something that would not be particularly 
englightening for the ZopeZen Masters who can write Python scripts in their 
sleep but could provide a tremendous productivity boost to the less-skilled 
people who can and should be doing a lot of the grunt work but need lots of 
handholding.

I've actually been tinkering a bit with a TOC for just such a manual but I'm 
swamped with other projects at work and this would be almost a full time job 
in itself.

Cheers

Lee Hunter



_________________________________________________________________________
Get Your Private, Free E-mail from MSN Hotmail at http://www.hotmail.com.