17 Apr
2010
17 Apr
'10
11:26 p.m.
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