On Feb 23, 2006, at 1:57 PM, Benji York wrote:
> But it's of course a judgment call.

Perhaps this is just one of those to-each-his-own things. <shrug> My own are doctests. ;)

Sure. I actually really appreciate reading good doctests, they help a lot, and they beat not having any docs at all any day!

A non-sequitur: For truly standalone packages, I suspect that people expect some form of non-executable narrative documentation to be included that ties the continued use of the package together with its implementation. In my experience, it's easy to get lured into thinking that you've documented a package properly because it has doctests and interface documentation, when in reality it probably needs some other form of documentation beyond the doctests (e.g. high- level overview of purpose, how to install it, what other packages it depends upon, which versions of Python/Zope it works with, who is responsible for maintaining the package, where to report bugs, and so on). I suppose this is really a packaging issue, but it would be nice if more packages in the zope namespace package were treated as "islands" like this that could be installed separately from Zope proper. It would also likely help prevent inappropriate dependencies from creeping in. Zope 2 wasn't born a mess of spaghetti dependencies, they just sort of grew like weeds over time.

- C

_______________________________________________
Zope maillist  -  Zope@zope.org
http://mail.zope.org/mailman/listinfo/zope
**   No cross posts or HTML encoding!  **
(Related lists - http://mail.zope.org/mailman/listinfo/zope-announce
http://mail.zope.org/mailman/listinfo/zope-dev )

Reply via email to