API.jquery.com Feedback

API.jquery.com Feedback


As a front-end designer for complex web-apps and freelance usability
consultant, I want to offer some feedback on the NEW jQuery API
section:
---------------------------------------------------------
1. Bookmarking / Browser Favorites
When using Ajax to populate pages, it is recommended to use an URL
hash-syntax to allow pages to be 'bookmarked'. This allows direct-link
to a topic to be copied and pasted into a discussion. Since I provide
support to jQuery users, I am constantly providing links like this one
to users:
http://docs.jquery.com/UI/Droppable/droppable#options
The new API does not provide a quick or intuitive way to create/copy
such a link. So I recommend that each time page-data is loaded, the
'path' to that data be reflected on the URL, like:
http://api.jquery.com/#UI_Droppable_options
A simple JS function can run on $(document).ready() to check for and
parse the URL hash when one exists - and load the corresponding data,
as well as put the 'main menu' in the correct state. This would
provide bookmark/favorite compatibility with very little effort, and
meet the basic usabilty requirements for URLs.
---------------------------------------------------------
2. Main Menu Usability
The current design of the main menu in the API is not ideal. Here are
a few ideas for consideration.
2-A. TOP-Level title/link
If the top-level of the menu is going to disappear when you start to
drill-down, then there should be a top-level 'header' to bring them
back. This is more intuitive than 'closing' an item. For example:
CURRENT Menu Display:
Attributes
HTML
html()
html(val)
RECOMMENDED Menu Display
API Menu (or 'TOP')
Attributes
HTML
html()
html(val)
By adding a top-level title/link to the menu - that is ALWAYS visible
- it provides a very intuitive way to return to the top-level links.
With this design, the "X" icons should be replaced with more intuitive
'arrows' that indicate that an item (eg, "HTML") is 'expanded', like:
API Menu
Attributes [v]
HTML [v]
html()
html(val)
2-B. Navigation for Power Users
The current drill-down method - showing only one menu-branch at a time
- is simple at the sacrifice of speed and flexibility. It is common
for developers to reference *multiple topics* and switch between them
as needed. IDEALLY, this could be done with *a single click*. The
current drill-down-menu can get back to the top-level with a single-
click, but then you ALWAYS have to drill-down to the specific
information - repeatedly. If you are switching between 2 different
topics, this means a lot of clicks!
A tree-list may seem old-school, but there is a reason they are
standard in applications: They are great for power users, and also
intuitive for beginners. For power users, the big advantage of a tree-
list is that *multiple sub-branches* can be visible at the same time,
allowing movement between any of them with just a single click. This
includes pages within the same parent-branch, but not in the exact
same branch - for example:
Traversing - Filtering - filter
Traversing - Finding - find
Traversing - Chaining - end
With the current menu, moving between these 3 closely related topics
requires navigating up/down, up/down, up/down - repeatedly!
It is even worse when the topics are not related. This means
constantly going back to the top-level menu and drill-down 3 or 4
levels each time you want to change pages - ie, up/down/down/down, up/
down/down/down.
It is even worse if you don't have the 'path' to the information
memorized, ie:
TOP - Manipulation - Inserting Around - wrapInner(elem)
It is easy to accidently go down the wrong path and be forced to 'back
up' and try again. For beginners and pros alike, it is frustrating
when you cannot *quickly* find the information you were looking at
earlier. A tree-list cures this by guiding you to previous topics -
because the 'full path' is still displayed for every page you have
viewed (if you choose to leave the tree expanded.
There are alternative ways to address these usability issues without
using a tree-list, but the tree-list is the easiest and most intuitive
option I can see at the moment.
---------------------------------------------------------
API usablity may seem unimportant compared to getting version 1.3 out
the door, but if a new documentation API is going to be implemented,
I'd like to see its design have the same high quality and usability as
the jQuery code. I have already encountered some of the annoyances
mentioned above, which is why I took the time to contribute this
feeback.
That's my 2-cents worth. Disagreement and alternate suggestions are
welcome.