[Zope] Zope Documentation

[Trevor Toenjes]

I think there are good points raised here.  Thanks for including me in the
thread.

It is interesting that Zope and community has created it's own Catch 22.
This power is also a stumbling block.
The power of having many options and approaches also creates confusion for
the newcomer to navigate and determine the best choice of direction in
learning and approaches toward solutions.

The first steps to build your first Zope website often creates enough
momentum to hinder the newbie from learning alternative approaches until
much later.  How many newbies think that the DTML_Document is that all
powerful object because it is what is used in most examples with
standard_html_header?  And then proceed to create a website with 100%
DTML_Documents, only to discover they have now defeated many benefits of
acquisition and folders?  And then you go back and convert everything to
DTML_Methods with folders containing properties.

This echoes my experience.  I got so involved with the simplicity of DTML
that it has taken me a long time to try and break the 'crutch' of using DTML
for everything.  A crutch is NOT good.

When a newbie has a problem, the only choice is to search mail list archives
and zope.org docs.  But these are heavily laden with DTML references and can
quickly send the newbie into the perception that DTML is everything in Zope,
which just isn't the case anymore.  I think it is a big mistake that the
Zope Book consider p-scripts advanced.  This should be considered a basic
requirement for newbies.

The community has long stated that newbies should be exposed to python
scripting immediately.  And I don't think we do a good job at that.  It is
too easy to become *mediocre* in DTML, which doesn't benefit the community
by creating talented developers.

The challenge on NZO will be to promote the flexibility of all the options
as a positive attribute.  Another approach could be to explain a quick
overview of the options...almost like an introspective critique.  We almost
need a community endorsed comparison of DTML, p-scripts, and external
methods and python products and the suggested appropriate situations for
each.

This comparison/overview could also serve as a warning to newbies that there
are many choices and that some are more Zope-esque and others are more
Python-esque.  And the current wave is that python-esque promotes more
flexibility, scalability and power.

How is that for trying to address both sides?
The hard work is sitting down to create this document.

-Trevor

Yvon, please help refine the Software Products GUI.  We welcome all feedback
and I would like to see how you want to apply your feedback to a solution.

> -----Original Message-----
> From: Breuer, Yvon [mailto:YBreuer@tee.toshiba.de]
> Sent: Monday, August 12, 2002 5:03 AM
> To: Dieter Maurer
> Cc: zope@zope.org; douwe@oberon.nl; zope@toenjes.com; jprice22@wvu.edu
> Subject: RE: [Zope] Zope Documentation
>
>
>   YB: Maybe we shouldn't talk about a true way, but about a
> *preferred* way.
>   DM: But your preferences are not necessary mine and mine even
> vary with context...
> I understand your examples and I see your point.
>
>   DM: I am very happy with the community's democratic nature. I
> would not like a dictator that decides on whether a product can
> or can not be on the products list.
> I agree!
>
>   DM: But I would welcome [1] an annotation service, where users
> of a product can comment in such a way that other users learn
> about their experiences (something like the reader reviews on
> Amazon.com). And maybe, [2] a preference rank for products in a
> group may help (something like the purchase rank on Amanzon.com)
> automatically determined from the number of downloads or derived
> from some explicit rating.
> All I've been trying to achieve was to get an improvement on how
> to retrieve whatever you need for a certain goal. I think the
> current documentation isn't clear enough in this matter. I _do_
> what I'm missing, but, because of my lack of experience, I didn't
> know (still don't) how it can be solved. While following the
> postings on the list I have the feeling this also applies to others.
> Maybe this improvement can be achieved by your [1] and [2]
> solutions! If others agree: Who'll set it up? (and how?)
>
>   DM: PS: you could learn to strip your quotings down a bit.
> I'll try... ;-)
>
> Yvon
>
> PS: "If others agree" --> Because I think the community should
> support it to make it use- & succesfull.
>