[Zope] Zope reference documentation?

Andreas Jung Andreas Jung <lists@andreas-jung.com>
Wed, 15 Jan 2003 22:58:44 +0100


--On Mittwoch, 15. Januar 2003 22:43 +0100 Milos Prudek 
<milos.prudek@tiscali.cz> wrote:

>> The Zope Book has a reasonable API references for ZPT, DTML/TAL (Appendix
>> A-C).
>
> No Andreas, it does not have that. It has an API reference, but not a
> comprehensive or reasonable one. Some core functions are simply
> undocumented. Maybe 10%, maybe less, but they have been undocumented for
> more than a year, maybe even two years!

Instead of crying around, you would better help working on the documentation
issue. The Zope Book is a more or less open project (Chris McDonough
asked several times for support). So everyone is invited to contribute to
a better documentation.

> And there are almost no examples. IMHO every function should have an
> example. Even the simplest function.  A definition is good, but examples
> are preferred by many. And don't get me started that examples do not
> belong to reference text. Make them optional, so that they can be turned
> off by people who dislike examples.
>
> Patrick Price sees this deficiency clearly, since he's a newcomer. Zope
> stalwarts are blind to these issues.
>
> I've been using Zope for four years now, and although documentation
> improved a lot since 1998, it is still the same relative distance from
> Zope abilities. And Patrick is either right that this is a funding issue,
> or <sinister=on>Zope Corp. ridiculously high consulting fees depend on
> the documentation deficiencies.</sinister=off>

ZC is small company and they must make money to survive. First for their
own sake and second for the sake of Zope. Without ZC Zope would be nothing
so don't complain about their fees. They have a lot of qualified people and
I am sure they are worth the money. At least ZC consultants work with more 
worth
than 95% of all consultants I know.

-aj