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)