[Zope] Giving up in frustration

[Paul Boddie]

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