Zope docs (was Re: [Zope] I was wondfe)

[Milos Prudek]

> I think folks need to start becoming more specific when they say "Zope
> isn't well documented".

Chris,

The following is a rant :-) 

Read the recent Digital Creations survey. Lack of documentation is by
far the most prominent complaint. That's not random people bitchin',
that's statistics :-)

Zope Book was no good before it went through editorial process.
Developers in DC write excellent software but horrible docs. They need
an editor to tell them that documentation is not only about pure
definitions, but it actually needs examples (and more examples <and yet
more examples>). And it needs repeating things that were already
mentioned elsewhere in the book, because people forget. Some people
outside DC (or at least myself) are not as bright as DC people. 

Now that we have CMF, DC is doing the same mistake as if it never
learned anything. There are no docs, just random data in the fishbowl.
Just look at it from a moron's perspective (a moron like myself) and you
won't be able to make any sense of the docs scatterer around fishbowl.

CMF is very exciting but I decided to not touch it before there are any
good docs. Standardised, revised, edited docs. 

A year ago I suggested (to Amos, I think) that DC hires a full time
technical writer, or a bunch of writers, or contract them. DC replied
that they will consider this idea. What happened instead was that the
programmers (Michel Pelletier and Amos Latteier) wrote the Zope Book,
and it required a long editorial process to make it readable and easily
understandable. 

In my humble opinion you should not let programmers write the
documentation. 

I am a poor programmer. I take very long to write a program. I enjoy
writing documentation. But bright, effective programmers do not enjoy
it.

Forgive this rant. I would not write it if I did not care about DC and
Zope. In my opinion, the documentation, be it Zope development, CMF, or
Products, is not something DC could be complacent about or satisfied
with.

Best regards

--
Milos Prudek