[Zope-dev] [Announce] API Documentation Fishbowl Project

[Dan L. Pierson]

--On Wednesday, June 06, 2001 11:50:43 AM -0700 jimbo 
<jimbo@tacomaplace.com> wrote:

> I hope this helps. I wanted to add my feelings on the whole documentation
> issue.  It seems to me that the whole process caters around developers
> too much.

I have to disagree with you **in the context of this thread** for two 
reasons:

1. DC has done a lot to improve the documentation for non-developers in the 
last year.  The Zope Book(s) should have a major impact when they start to 
appear on shelves in the next month or so.  Developer documentation has 
lagged behind.  This thread is about a proposal to improve developer 
documentation.  It says nothing at all about the other *existing* efforts 
by DC and others to improve other types of Zope documentation.

2. One of the main points DC made at this years Python conference was that 
they have tried to focus the Zope core on too many audiences at once.  They 
had to have a clearer focus and chose developers as that focus.  Of course 
I like this choice because I am a developer, but the more important point 
is that this tighter focus has the potential to make life easier for all of 
us.

For example, the CMF is focused on content managers.  It is implemented as 
a *separate*, *layered* product on top of Zope.  This means that it is free 
to make tradeoffs in favor of content managers that the Zope core isn't. 
It also means that CMF release schedules are not tied to Zope release 
schedules.

Incremental restructuring of the Zope core and improved Zope developer 
documentation makes it much easier and more practical for DC and others to 
create layered Zope products that address other communities.  Continuing 
the current rather inscrutable nature of the Zope core makes all of this 
harder for everyone involved.

Dan Pierson,
Control.com, Inc.