In anticipation of next week’s jQuery 1.4 release we’re revealing the brand new jQuery API site. Not only is this a complete redesign of the existing API site but it’s also a complete rewrite. Every single method has been rewritten from the bottom-up to provide the best possible information about how jQuery works.
API Documentation Rewrite
A couple months ago the jQuery team sat down to start rewriting the API documentation in anticipation for the 1.4 release. We were working with team member Karl Swedberg, one of the co-authors of Learning jQuery and the jQuery Reference Guide, and in reviewing his work on the next version of the jQuery Reference Guide came to the conclusion that he had written a superior resource. We contacted Packt publishing and came to agreement wherein the project would receive the contents of the jQuery Reference Guide so that we could use it and publish it on the API site as we see fit.
This is a huge coup for the jQuery community: I think you’ll find, when looking at the improved documentation, that the quality is dramatically improved over the old docs. There are more explanations, more examples, and the documentation has been made current with jQuery 1.4 wherever possible (there are still some gaps that we’re looking to close before the release but we’re very nearly there).
The new version of the jQuery Reference Guide, based upon this rewrite of the jQuery API, is coming out soon. I recommend watching the Packt publishing web site for more announcements.
We should mention that we’re working on a final set of licensing for the site’s contents. Once the final ducks are in a row we’ll be releasing the entire contents of the site under a Creative Commons license for all to use as they see fit.
API Site Redesign
The entire API site has been redesigned. We’ve taken special care to try and integrate many of the requests that’ve come in from users to improve the overall quality of the site.
API Home Page
To start you’ll notice that the API now has a dedicated sub-domain focusing completely on jQuery API:
https://api.jquery.com/
(Note: The old docs.jquery.com API pages will remain intact for about a week or so, so that we can make sure that everything is transitioned over, then we’ll set up the final redirects to the new site.)
This main landing page is optimized to get you to the methods that you want, as quickly as possible. The main page has every single jQuery method, property, and selector listed on it – you can scroll through the full list, or browse through the extensive category list on the side, or you can simply begin typing. When you type on the jQuery API homepage all the API entries will be instantly filtered.
Categories and Versions
One of the areas that we wanted to see improved in this iteration of the site was the quality of categories provided. To start, we’ve expanded the number of categories from our traditional jQuery module structure to become more comprehensive (and include topics like forms and plugin authoring). Along with this expansion we made it so that API entries could co-exist in multiple categories simultaneously. This will make it easier for you to find the entries you’re expecting, where they should be.
Additionally, and perhaps more importantly, we’ve added information to every single method, property, and selector in the API showing in which version they were added to jQuery. For example, you can see all the pieces of the API that were added, or changed, in jQuery 1.4 (Note: The aforementioned page is nearly complete, it’ll be more-so in time for the final 1.4 release next week). We have version information for every entry, going all the way back to jQuery 1.0.
API Entries
Individual API entries are not only easier to read but they’re also easier to find. You no longer have to divine which category an API entry might be in: You can simply access the name directly. For example:
When viewing an API entry you’ll likely note a few major changes: No more tabs hiding important entry content, clearer page organization, and most excitingly: A new, inline, commenting system.
As part of the move we’re moving away from using a wiki to power the API site. While it was nice to receive the occasional contributions from users those additions were far outweighed by the piles of spam that the wiki got. Now you can feel free to use the inline comment system to talk about the API entry, provide samples, and offer corrections. The jQuery team will be monitoring the comments and will periodically integrate recommended changes.
Performance and Backend
As mentioned before, we’ve switched away from using a MediaWiki backend to a new WordPress-powered backend. So far we’ve been very impressed with the performance. Every single page on the site is heavily cached and gzipped – with all media being served up from our CDN. We think you’ll find it to be a significant performance improvement over the old docs site.
jQuery API XML Dump
A big part of the rewrite of the new backend is that we can now provide a uniform XML dump of the jQuery API. Historically we’ve provided a Python script for scraping the contents of the wiki site but now we’re just going to provide that file directly and immediately to you. If you’re developing a tool that provides alternative views for displaying the documentation you can feel free to use the file as you see fit.
Thanks
I want to thank the whole jQuery team for their support but specifically Karl Swedberg, Jonathan Chaffer, Paul Irish, Boaz Sender, John Resig, Richard Worth, and Scott Jehl for their hard work in rewriting the documentation and making this site come to life. It was many hours of tedious work but we hope all will benefit from it in the end.
