Re: RFC: Proposed new style for documenting and testing ZTK packages
Chris McDonough <[email protected]>
| Newsgroups | gmane.comp.web.zope.devel |
|---|---|
| Message-ID | <[email protected]> |
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 _______________________________________________ Zope-Dev maillist - [email protected] https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )