4 ms·

I still long for the old http://docs.jquery.com http://docs.jquery.com from the 1.3.x days. The new site that actually serves all the material, api.jquery.com,

by pak 16y ago

I still long for the old http://docs.jquery.com http://docs.jquery.com from the 1.3.x days. The new site that actually serves all the material, api.jquery.com, feels like exactly that--an API reference--while the old format was much more browsable. Instead of just alphabetical lists of methods you got a fuller explanation of what each function did, and the methods in each section were organized by purpose with surrounding explanations, not as a sterile alphabetical list. A world of difference to the newcomer. Had the docs been the way they are now, I'm not sure I would have been so happy to read them and get started.

jeresig 16y ago
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/ http://api.jquery.com/category/events/ Detailed explanation and categorization of the event object properties: http://api.jquery.com/category/events/event-object/ 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 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.
- pak 16y ago
  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/ http://api.jquery.com/category/selectors/ Old: http://web.archive.org/web/20080516171346/docs.jquery.com/Selectors 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 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.

by pak 16y ago

jeresig 16y ago

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/ http://api.jquery.com/category/events/ Detailed explanation and categorization of the event object properties: http://api.jquery.com/category/events/event-object/ 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 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.

pak 16y ago
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/ http://api.jquery.com/category/selectors/ Old: http://web.archive.org/web/20080516171346/docs.jquery.com/Selectors 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 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.