[Zope3-Users] Re: [Zope] Debugging doctests

[Chris McDonough]

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