OK, this is brilliant.

Obviously I should rewrite my "open-source project truisms" post in this manner... another time, perhaps.

Speaking of which:

Open-source project truisms: feedback

Marius Gedminas suggests also making your source code repository browseable through the Web, and Scott Lamb boils much of my advice down to "use Trac". That way, you get a source-code browser & a Wiki, too, so that people can correct things on the site themselves. Michele Simionato came out against Wikis (in a separate exchange a few days ago) but I'm on the fence & slipping towards the side of the Wiki... I think they do more good than harm ;).

Marius also suggested putting up screenshots -- that's not applicable to developer libraries, but is a great idea for anything a non-developer/user is expected to touch.

On a somewhat separate note... Python docs

Submitting patches to Python is a huge pain, because of all of the overhead and review process. (And the sourceforge bug/patch system is really, really lousy.) This process is certainly legitimate for code, but I think it's overkill for documentation -- especially when you consider how the standard library has grown, and how poor the documentation is in some of the places I frequent (urllib2, anyone?)

One possible solution?

I've been thinking setting up a Trac site and a darcs repository for editing Python documentation. The idea would be to use tailor to maintain a synced darcs version of the CVS/SVN documentation, and then build additional documentation off of that darcs base. The additional docs could thus be maintained in concert with the standard docs, but without the hassle of making them formal. Heck, with proper integration, the Trac wiki system could augment the whole thing, too.

I'm balking because I've had some recent experiences with darcs that suggests that it may not be ready for this kind of role. More anon. Thoughts welcome, however...

--titus