News for hackers. Stuff that matters.
Re:JQuery deconstructed by jeresig on Tuesday July 20, 2010 @05:04PM (#1533449)
I've read your comment a couple times now but I'm struggling to think of an example that hasn't improved with the new layout. Not only does the new layout include a much more in-depth listing of properties and methods but it also has a much more dynamic categorization system. Perhaps you missed all the categories available on the sidebar of the site?

For example, all the method and properties relating to events: http://api.jquery.com/category/events/

Detailed explanation and categorization of the event object properties: http://api.jquery.com/category/events/event-object/

We studied how users were interacting with the jQuery documentation and overwhelmingly they were ignoring (and out-and-out confused by) the categorization and going straight to Google - because they wanted to find methods by name or functionality. For this reason we improved our search functionality and made the URLs super-intuitive (.html() is now just http://api.jquery.com/html, for example).

Note that the rest of the "old" documentation is still in place - this includes all the tutorials and other getting started guides - the only thing that was "moved" was the API documentation. Undeniably the browsability of the API docs has improved with this revision.

Re:JQuery deconstructed by pak on Thursday July 22, 2010 @12:49AM (#1537388)
You're right in that the old docs had really bad searching. That's much improved in the new docs.

I might be different. I came to learn jQuery through the raw docs, not through tutorials, and found that the old docs' organization was more friendly for casual browsing & exploration, and the new is more amenable to API lookup ("I already know the name of the method").

For example, compare the selectors page:

New: http://api.jquery.com/category/selectors/

Old: http://web.archive.org/web/20080516171346/docs.jquery.com/Se...

(The CSS is very broken on the archive--) but you can see that you used to have it organized functionally, not alphabetically, which was great for me as a learner to see at a glance the different axes of capability for jQuery's selector engine, instead of a alphabetical mash of selector operators, some titled by the operator, others by a description. If I didn't already know CSS thoroughly, reading your selector operator list now would be very disorienting.

I have to say jQuery and its community is amazing, without it QuickFuse (http://quickfuseapps.com) would not have been possible. But one of its strengths was being able to be grokked so quickly by newcomers, and I was a bit disheartened to see the docs stray away from a introductory format more in favor of a reference format. It's a bit more intimidating to the newcomer to have to wade through categorical tagged lists of methods with brief descriptions, instead of a human-organized page on each aspect of the jQuery object that presents the methods in a sensible order.