Jim Fulton wrote:
On Mon, Sep 21, 2009 at 11:19 AM, Martijn Faassen <faassen@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