[Zope] Zope reference documentation?

[Chris McDonough]

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:
> >=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:
>=20
> > You can do this yourself, at least for the Zope Book.  The online
>=20
> You can, but sometimes your comments will be ignored.
>=20
> Example:
>=20
> June 20, 2002, Anonymous user comments that "manage_addDocument should=20
> be manage_addDTMLDocument! if you use manage_addDocument, you=B4ll get =
a=20
> DTML Method..."
>=20
> Jan 10, 2003, Anonymous user comments that "manage_addDocument creates =
a=20
> DTML Method. manage_addDTMLDocument creates a DTML document. This has=20
> been pointed out 6 months ago, and still no change in Zope Book."
>=20
> 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.
>=20
> Another example:
>=20
> 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.
>=20
> 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.
>=20
> 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
Chris McDonough <chrism@zope.com>
Zope Corporation