On Jul 31, 2009, at 12:32 PM, Reza Lotun wrote:
Even if I re-suggested the wiki based documentation, I think it's important to be extra careful on how it's used. One thing I personally hate is projects whose documentation is basically wiki-based, and what you end having is a disconnected set of tips, many out of date, of how to do this and that. It could be OK it it's labeled 'Tipi-wiki' but not 'Documentation' :).
I agree - the wiki shouldn't *replace* the documentation, but the reality is I have loads of bookmarks of blog posts and discussions on the mailing list, and it'd be nice if I could to go one place to find all that type of info. A "recipe" or "cookbook" wiki might be all we need, with the ability to comment on each. The Activestate Python Cookbook is kinda what I'm thinking about: http://code.activestate.com/recipes/langs/python/
I agree with all of the above. A wiki is nice when there is no suitable formal documentation available for a topic. I think I may have used the aphorism once before, "documentation is like sex, when it's good, it's great, when it's bad it's still better than nothing." (no offense intended to any with delicate sensibilities, btw ;-) My only question about Sphinx, isn't it just for API docs? Also, can it interpret Zope interfaces like pydoctor can? Personally I'm pretty happy with the API docs (although there's always room for improvement in the actual docstrings), I think if there's a documentation need that's more dire, it's the long-form instructional kind. I just don't want to sidetrack *that* discussion by getting into API documentation concerns. -phil