-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.
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.
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.
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"
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.
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.
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.
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.
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?
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.
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...
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.
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.
-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.