[Zope-dev] Why I dislike narrative doctests

[Jim Fulton]

On Apr 25, 2008, at 11:22 AM, Stephan Richter wrote:
>> - A variation is to have a narrative that doesn't try hard to be
>> documentation.  The narrative can be convenient, up to a point, even
>> in a test.  These should be clearly marked as not being  
>> documentation.
>
> Why is this not documentation?

Because it's written primarily as a test, not as documentation.  For a  
file to be useable as documentation, greater thought needs to be given  
to the user reading it.  Sometimes, I can't afford the extra time.

Jim

--
Jim Fulton
Zope Corporation