[Zope] Zope reference documentation?

[Milos Prudek]

Chris McDonough wrote:
> On Fri, 2003-01-17 at 03:59, Thieu-Hon Tran wrote:
>=20
>>Would it be asking too much or be inappropriate to put something
>>similar to your short explanation into the first paragraph of the
>>ref-doc of the class REQUEST? Maybe just something like:

> You can do this yourself, at least for the Zope Book.  The online

You can, but sometimes your comments will be ignored.

Example:

June 20, 2002, Anonymous user comments that "manage_addDocument should=20
be manage_addDTMLDocument! if you use manage_addDocument, you=B4ll get a =

DTML Method..."

Jan 10, 2003, Anonymous user comments that "manage_addDocument creates a =

DTML Method. manage_addDTMLDocument creates a DTML document. This has=20
been pointed out 6 months ago, and still no change in Zope Book."

Maybe the reasoning here is that since it is in the comments, it does=20
not need to be integrated in Zope Book. I do not agree with this=20
reasoning. Such valid comments should be integrated in the Book and=20
deleted from comments.

Another example:

manage_delObjects. Why is this method top secret? It is IMHO quite=20
essential method. And it was pointed out in comments by xqvverty - Sep.=20
13, 2002 9:53 pm.

IMHO documentation should be managed by a full-time employee. Chris is=20
doing it, bot certainly not full-time. I even believe that this job=20
should not be carried out by anyone directly developing Zope.

I've been in both shoes, working sometimes as developer, sometimes as a=20
documenter, and sometimes both. In my experience, I was a poor=20
documenter of my own work. Programmers seldom create good documentation=20
of their own work. Documenter should be independent, and should have=20
free access to the developers to ask questions.

--=20
Milos Prudek