[Zope] Zope reference documentation?

[Paul Winkler]

Speaking only for myself and Peter Saibaini (sp?), when
we tackled the Advanced Scripting chapter for the 2.6 version, we
really did try to address *all* comments except a very few that
seemed really irrelevant to the chapter.

There is now a *lot* more stuff about zope API methods in this
chapter.

On Fri, Jan 17, 2003 at 02:54:30PM +0100, Milos Prudek wrote:
> 
> 
> Chris McDonough wrote:
> >On Fri, 2003-01-17 at 03:59, Thieu-Hon Tran wrote:
> >
> >>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 
> be manage_addDTMLDocument! if you use manage_addDocument, you?ll 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 
> 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 
> not need to be integrated in Zope Book. I do not agree with this 
> reasoning. Such valid comments should be integrated in the Book and 
> deleted from comments.
> 
> Another example:
> 
> manage_delObjects. Why is this method top secret? It is IMHO quite 
> essential method. And it was pointed out in comments by xqvverty - Sep. 
> 13, 2002 9:53 pm.
> 
> IMHO documentation should be managed by a full-time employee. Chris is 
> doing it, bot certainly not full-time. I even believe that this job 
> should not be carried out by anyone directly developing Zope.
> 
> I've been in both shoes, working sometimes as developer, sometimes as a 
> documenter, and sometimes both. In my experience, I was a poor 
> documenter of my own work. Programmers seldom create good documentation 
> of their own work. Documenter should be independent, and should have 
> free access to the developers to ask questions.
> 
> -- 
> Milos Prudek
> 
> 
> _______________________________________________
> Zope maillist  -  Zope@zope.org
> http://lists.zope.org/mailman/listinfo/zope
> **   No cross posts or HTML encoding!  **
> (Related lists - 
> http://lists.zope.org/mailman/listinfo/zope-announce
> http://lists.zope.org/mailman/listinfo/zope-dev )

-- 

Paul Winkler
http://www.slinkp.com
Look! Up in the sky! It's MEGA ENERGY WARRIOR SNAKE!
(courtesy of isometric.spaceninja.com)