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
_______________________________________________
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users
