jQuery comments on WordPress

Info from Karl Swedberg, docs lead for jQuery:

"We currently use WordPress to manage the documentation. Each entry uses a custom XML schema that we process through XSLT to produce the HTML on the site. You can see the raw XML dump at http://api.jquery.com/api/". The XML file "is an amalgamation of many WordPress entries that are in XML format... the API is also available via JSON(P) at: http://api.jquery.com/jsonp/ . And it's searchable via query params that you send to the URL along with your request. ( example at http://test.learningjquery.com/jqas/ )"

"The XML is stored in the WP database as WordPress entries. This is not ideal, for obvious reasons. The XSLT is snow (finally) on GitHub, along with the rest of the WordPress install, although it's currently a private repo."

"[WordPress] has built-in search and category management, as well as author/editor roles. One weakness is the high barrier to entry for people contributing to the documentation. [ed. note: not sure I see a high barrier?] Another weakness is the lack of version snapshots. We're kicking around the idea of having some mechanism by which we can keep documentation in static files and push them to GitHub, with some post-commit hook that will update the WP database."

They don't use any auto-generated docs:
"We tried jsdoc a while back, but it made the jQuery core less readable for people working on the code itself."

They don't version their docs:
"This is something that we're actively working on but don't have a viable solution for yet."
[ed. note: We could store the generated HTML in gitHub and tag it. It's not versioning the WordPress content directly, but at least it captures a reproducible snapshot of the docs.]

They do not allow community editing of the docs:
"We support community feedback. For a long time up until jQuery 1.4, we used a wiki in which the content was editable by anyone who registered for an account. That proved problematic, however, with a lot of spam showing up and inconsistent style and level of detail across the API. Currently we allow comments through Disqus, but we're about to get rid of that, too. In its place, we'll have a form that people can fill out if they see errors or omissions."