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