Joe Grace <occam@serv.net> wrote: [...]

The novice's job is to get up to speed as rapidly as possible with all the basics so that s/he can really get stuff done as soon as possible. That's the best support Zope can ask for from newbies.

Unfortunately, without up-to-date and complete basic documentation, that's very difficult.

The basic documentation issue is probably the most important thing. Until now I hadn't played with Zope 2 at all, apart from a download of an alpha a few months ago, but I have been playing extensively with the Zope 1 series. In addition, one's definition of the basic documentation is going to depend on where one comes from: I came to Zope through its predecessors and really wanted good documentation on DTML and product development.

I've wasted *days* due to oversights in Zope documentation. I didn't know enough to know that something was missing, but I did know I was new to Zope and had no right to believe Zope had bugs in such basic stuff (which it didn't). Eventually, I came around to questioning the documentation.

[...]

Now, I'm trying to upgrade to another level of Zope knowledge, and I know the docs are incomplete (from my previous experience with them and now that I know enough to wonder "Where did you say that file belongs? Doh, you didn't.")

I have noted in the past that the documentation, whilst very persuasive on the merits of Zope and rather in-depth in describing some of the mechanisms involved, frequently omitted to tell the reader the most elementary starting-off details such as where to put files and how to get Zope to recognise them.

Ok, here's one big suggestion for Zope. Include in the initial Zope database, all the example projects from the docs (but in a sample directory which won't get in the way of trying to install the documentation examples as written). That way, newbies don't have to learn how to put the projects in the database before experimenting with them. Also, if the installation goes wrong, the newbies have a running example to compare against to see where they went wrong. Then document the heck out of the installation procedure. Also, create all the file system directories necessary for the documentation projects to be used, e.g., Extensions, etc, as part of the basic Zope installation. Finally put README's in those directories explaining what the files there are for (samples, examples, etc., and links to relevant documentation).

A good idea. It is to an extent a little sad that the best way of creating products implementing, for example, DTML tags is to copy an existing product and then to start cutting and pasting source code. With some constructive documentation to hand giving good advice on how to put things in the different directories, possibly with some template files hinting at how the different ways of extending Zope can be built "from scratch", I think we could get past this stage. Paul