Thursday, August 21, 2008

SciPy conference - afternoon

SciPy Documentation Editor:
NumPy decided, instead of creating a bunch of documentation, to create a documentation *framework*! This looks really useful for open source projects. And the sources are available to use elsewhere. We definitely should look at using this for other python projects.

Documentation appears to be the theme of the afternoon sections. It's nice to see that documentaiton is getting attention here. Too often it's an afterthought (if at all.)

Sphinx is a python documentation generator. Currently used in matplotlib. Sphinx avoids separate "printed" and "online" docs. Based on reST. Again, this looks good.

In general, most docs suck. Too many say things like: "xyz is the foo port of bar", which only works if you're coming to foo from another OS or Package that uses bar. Some folks are going directly into foo - and needing to know what the heck xyz does and how to use it. Setting up frameworks that *work* provide easy entrypoints for folks to contribute to an OpenSource project - even if they're not 1337 hackers itching to commit patches to the core.

No comments: