[Zope-dev] RFC: Proposed new style for documenting and testing ZTK packages

[Chris McDonough]

On 4/17/10 5:20 PM, Tres Seaver wrote:
>
>> - Documentation should be written for documentation's sake. The
>> emphasis should be on helping people understand what the software is
>> for and how to use it, *not* on coverage.
>
> Amen.
>
>> - Documentation should be executable.  Manuel helps a lot for this.
>
> Amen.  The Sphinx tools for this are pretty neat, too.

Documentation needn't be executable.  Documentation should be right.  But 
sometimes documentation is just documentation and automating the checking of 
its rightness isn't reasonable, especially if making it executable takes the 
slightest bit of meaning away from it as documentation.

Sorry.  No free lunch here.

- C