JQuery's API documentation gets a redesign | Hacker News Reader

JQuery's API documentation gets a redesign

api.jquery.com

128 pointsjorde53 comments

Not a fan of this redesign.

-What happened to the comments? That was one of the most useful features of the old documentation, and I constantly relied on them to find examples or clarify edge cases.

-The code samples are on opposite colored backgrounds, which makes the whole page extremely painful to read. Can you imagine reading paper book that had code samples written in white text on a black background? How is that a good idea on the web?

-The huge blue border around the edge adds even more visual noise.

-Why is so much stuff laid out inside of boxes, starting with the list of functions? Developers are experts at reading raw blocks of text, so minimal formatting is needed.

-Finally, where did the old documentation go? The content has been changed, but where can we find it? There doesn't seem to be any links.

The old documentation definitely needed some work, but these improvements have brought with them new problems, and overall I find it harder to use than before.

Edit:

Compare Google's documentation: https://developers.google.com/maps/documentation/javascript/...

While not perfect, it does a lot of things right: no extraneous formatting around the page edges, solid background, clean code examples, and importantly, access to old versions of the documentation.

After experiencing the wall of well-intentioned garbage that is php.net I no longer like comments in docs. Those examples and clarifications of edge cases should be in the documentation itself.

And how do you discover these edge cases if you don't have comments? The point of the comments is to point out common issues, use cases and potentially, common misunderstandings.

Completely agree. This redesign feels claustrophobic. I prefer some of the newer API doc styles, like:

http://underscorejs.org/ http://expressjs.com/api.html

I have good eyesight, but I have a hard time reading the grey text between the strong code examples in the expressjs documentation. Also, the visual border around the examples is too subtle for me. I may look nice and fresh, but its just plain hard to parse visually. Certainly not a good example.

Comments have been disabled long before this redesign.

FYI, I am working on a revamp of jQAPI, a alternative browser for the documentation. Should be released pretty soon.

http://pre.jqapi.com/ https://github.com/jqapi/jqapi

So you're the guy! Thanks for the site, I use it every time I'm using jQuery.

Glad you like it!

Thank you, thank you! Has been a much needed replacement to JQuery's awful docs. Hope you can up the bar again!

You are welcome!

Wow, thanks for building this! It's leaps and bounds more usable (and fast) than the official jQuery docs.

Thanks! That's what I pursue.

Just wanted to say that I also always use your site. Super fast too!

Sweet! The new site is even faster because of the converted JSON format.

i must say jqapi's quick inline search is a win! Has been on my bookmarks bar for well over 2 years now!

Thanks

Wow! Thanks for staying around :).

I would have liked it the jQuery API documentation would be closer to the PHP.net documentation. For instance, I want to know the options for $.post - going to http://api.jquery.com/post/ would sure be nice (and even if it didn't exist, it could do a search for "you might have meant...")

For people unfamiliar with PHP.net's configuration, going to php.net/<function or whatever name> will go to the function if its known or search if it isn't (like http://php.net/strapos)

Perhaps something changed since you posted this, but when I view the documentation, the URLs do appear as you would have liked. Just substitute "$" with "jQuery"

Some examples: http://api.jquery.com/jQuery.post/ http://api.jquery.com/remove/ http://api.jquery.com/last/

It does work like that http://api.jquery.com/addClass. Wrong URLs could use some work though.

Here you go: https://gist.github.com/4477015

Replaces and error page in WordPress with a search for the request URI. Now we just need someone at jQuery HQ to use it.

Still uses WP's built in search functionality, which is less than great.

Consider talking to eddiemonge or one of the other team members on freenode about this:

Getting involved (http://docs.jquery.com/Getting_Involved): Additionally most of the jQuery core development team can be found in the #jquery-dev IRC channel on irc.freenode.net.

Another feature of php.net I wish this had: a "Related functions" or "See also" section.

This would be useful actually. I wrote "if !hasClass addClass, else removeClass" countless times until I figured, hey, maybe jQuery has a toggleClass function, I should look it up. These situations could be avoided if a "related functions" section was there.

I like the idea, but it's far more spread out than the previous design, and it's a bit much for me. I wish there was a google-like 'cosy' setting allowing me to compress things back a bit.

Every redesign on the web boils down to having less information on the viewport, requiring more scrolling, thanks to bigger font and wasted "Comfortable" spaces. It drives me crazy.

At least Google offers you a "Condensed" layout.

Man, how about finishing that jQuery plugins site instead of a redesign? :)

I would imagine the new plugins site would integrate with this Documentation site, or at least follow a similar design pattern.

Different people might be involved with each initiative.

Nice update! Much appreciated improvements.

The only thing I noticed that was weird is the search box seems to have different behavior between the instant results and the results you receive when you hit <enter>. Not sure if this is intended, but the instant results seem to be limited to whatever categorical scope you're in.

This is still slow as shit, why? It seems to be running under php when the whole thing could've been generated with jekyll and maybe even pjax'd to make navigation even quicker.

Any website "could be generated with jekyll" but you're totally ignoring the benefits of maintaining content with a dynamic site.

Just on HN, right now it's close to the #1 position; likely this site is getting hit with massive traffic as we speak, from diverse sources. Wait until that dies down before passing judgment.

It's Wordpress apparently.

I might not be in the majority here, but I like the redesign. Some of the entries might not be as complete, but I'm glad the comments section is gone because lets face it rarely was there anything useful in the comments, this isn't php.net.

Overall, this is a great update for the jQuery docs! It feels much more clean, and is a lot easier to navigate. My only complaint would be the dark code blocks, does it bother anyone else's eyes?

I personally like the dark code blocks. It's the blue they chose for the background that bothers me a bit.

If you ask me, making the old one faster would have been much better; I don't go there for the nice design, I go because I have stuff to get done, and I'd rather get that stuff done fast.

This was so needed, don't know why people are hating, it's much easier to read and browse through. Thanks for the update.

I don't know if I am alone, but having no global view of methods in a category without scrolling down is a noticeable loss of productivity for me. I, too, would prefer a "cosy" setting of some sort.

When people start to make cheatsheets then it means your documentation lacks some bird's eye view...

The logo does not waste enough screen estate.

Were comments removed or is it just me that can't see them?

I am hoping they come back, but guessing they were intentionally removed. I found the answers to many edge-case problems in the comments, and some might be hard to include in the docs specifically because they were version dependent or just not as intended. I agree that ideally those answers would be in the docs.

Sorely needs a bit more line height on the doc content. Terribly unreadable all bunched together.

This is a nice looking redesign but I think I'll probably stick to jqapi.com for quick reference. It's fast, I can find methods by URL (eg. jqapi.com/#p=get), and search auto-completes.

It looks nice, but the previous design was excellent. It had more examples, more detailed explanations, and lots of comments. I'll just have to get use to this.

Has been in development for awhile so I'm glad to see the team finally got it live. Although the jQuery UI docs page is still pretty ugly.

Neat!

How about adding a link which will let you experiment using jsbin (or sth similar) with the code examples?

This is what I use: http://oscarotero.com/jquery/

I prefer the "jQuery API Browser" which is available on the chrome web store.

$(".post").css("background-color","inherit").css("border",0);

The code-examples look awful in Chrome on Windows... :-[

Can you expand on that? I'm using Chrome 23.0.1271.97 m on Windows 7 Pro and it looks fine to me. The visual display is legible and very clear.

Reply on news.ycombinator.com