Have you noticed that for the 2.6 edition of the Zope Book at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition, we've addressed and edited out all of the comments in every chapter so far except for three "main" chapters and the API ref? Many people have helped to do this. It has taken on the order of maybe... 600 man-hours to do this. The remaining three "main" chapters are in progress. The API ref isn't, but should be, and adding a comment to it in the 2.5 edition will make sure it doesn't get lost in the email ether. Just because a comment is old doesn't mean it won't get addressed. This stuff takes time. And yes, I you're absolutely right. In a perfect world, someone other than a developer whould edit the Book, and yes, it would be a paid full time job. But things are the way they are, and nobody is willing to pay for it. ZC isn't willing to pay for it, nor should it be their obligation to do so. Are you? Annoyed, - C On Fri, 2003-01-17 at 08:54, 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. -- Chris McDonough <chrism@zope.com> Zope Corporation