I just heard on the new jQuery podcast that jQuery docs will be getting comments. jQuery just got a whole - even more - useful. This is direct from the horse’s mouth, an interview with jQuery head honcho John Resig.

I’ve felt for a long time jQuery has been ahead of the pack with its documentation, and since then both jQuery and its docs have gone from strength to strength.

One thing I was still missing though is user comments.

PHP leads the way here, with the official API docs allowing user comments at the bottom (example). No-one can anticipate all the issues that will arise, so why not open up docs to the developer community? Allowing user comments is also an easy way to help keep the docs up to date (if something of a compromise.) It could also be done as a wiki, if the wiki is managed well. (The Rails wiki is a good example of a well-maintained wiki that receives frequent contributions from people in the know.)

I was missing it until I heard that announcement. Again, jQuery’s leading the way.

I realise there are spam complications, but user comments are a no-brainer for making documentation useful. I continue to derive huge benefit from user comments. (To wit: The user comments about random number seeding were of vital importance in the making of the site I realised earlier today. I use them pretty much every time I have a PHP problem.)

I’ve even thought of making such a project myself, so much did I miss doc based comments.

The docs are being migrated from MediaWiki to WordPress. FWIW I think the OWF could benefit from a similar architecture if the wiki is going to engage with the community. As I’ve learned from AjaxPatterns and maintaining the tiddlywiki comments plugin, most people would rather append comments than updating a wiki. Updating a wiki is intimidating for some, and in any event, requires much more thought in order to make it coherent. Comments tend to be easier to moderate too because of their atomic nature.

Anyway, great news for jQuery and the community!