[Zope] reality check

[Christopher Petrilli]

On 12/10/99 8:06 AM, Jason Cunliffe at jasonic@nomadicsltd.com wrote:

> [snip]
>> While it hurts, it's not far from the truth. Have you considered putting a
>> guy/gal on documentation exclusively? In the projects I have encountered in
>> real life (if I can be said to have such a thing ;), I've found this provides
>> the most consistent and best documentation. A person who's only job is to
>> interact with the staff and provide legible information on what they
> produce is
>> a godsend.
>> 
>> I know it costs money, but your product really deserves it.
> 
> As a matter of practical interest - how much would it cost to hire someone,
> and for how long to improve the Zope docs to the next user-friendly level?

We do have someone hired purely as a tech writer, but we also have to have
the material to do the work with, and most of our people are working on
other "paying" projects.  In the end the company does have to flow cash.
The ZDP project has been doing an admirable effort at attempting to get more
documentation written, but the job is not as easy as it looks at the outset.
Writing good documentation is not easy.  Witness most products.

While the documentation of Zope is not great, I'd take offense that it's the
"worst" on the market.  You've obviously not experienced the problems of
voluminous documentation that is simply wrong, for the wrong version, or
unindexed.  10,000 pages without an index is less useful than 1000 with.

> What is the real demand now for this?
> How many here would be willing to contribute [how_much] towards this?

This needs to move to the ZDP list.

> Perhaps it is still too soon for Zope - perhaps not.
> I hope the recent announcements by DC mean that much better docs will be
> forthcoming soon..

We're working on it, but remember this is an OPEN SOURCE project, which
means that the community is encouraged to participate.  If you dislike a
section of documentation, you need to be specific in what you need
documented past "It sucks", exact examples you think would help, etc.

Chris

-- 
| Christopher Petrilli        Python Powered        Digital Creations, Inc.
| petrilli@digicool.com                             http://www.digicool.com