[Zope-dev] Proposal: Determining packages which are in the ZTK

[Martijn Faassen]

Jim Fulton wrote:
> On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen
> <faassen at startifact.com> wrote:
>> Documentation in 'docs' would disqualify
>> just about any package (and Reinout brings up a few objections).
> 
> I definitively want the option of making documentation executable.
> 
> Manuel makes it a lot easier to make good documentation executable.  I
> think the bobo documentation are a pretty good example of narrative
> documentation.  They are tested using manuel.  Interestingly, the
> parts I didn't initially test with manuel turned out to have lots of
> typos. :)

I agree we should continue to explore executable documentation and there 
is a lot of potential for manuel and a good example in the bobo 
documentation.

At the same time, I wouldn't want "we want executable documentation" to 
be a roadblock for documentation writers. Setting up executable 
documentation can be quite hard.

If we can get people to write narrative non-executable documentation at 
all we should support them fully.

So, I'd be against any "you can't contribute documentation unless it's 
executable" rule. The value of narrative documentation is tremendous, 
automatically checked or not. Hopefully there are also iterative ways to 
get from non-executable to executable documentation.

Regards,

Martijn