

JQuery's API documentation gets a redesign - jorde
http://api.jquery.com/#redesign

======
akamaka
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/...](https://developers.google.com/maps/documentation/javascript/tutorial)

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.

~~~
xnxn
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.

~~~
Narkov
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.

------
mustardamus
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>

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

~~~
mustardamus
Glad you like it!

------
ecaron
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>)

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

~~~
Mahn
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.

------
fredley
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.

------
sebnukem2
_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.

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

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

------
cgarvey
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.

------
r4vik
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.

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

------
DigitalSea
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.

------
bluetidepro
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?

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

------
gabipurcaru
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.

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

------
ckarmann
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...

------
conradfr
The logo does not waste enough screen estate.

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

~~~
LocalPCGuy
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.

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

------
imjared
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.

------
TommyDANGerous
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.

------
fourstar
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.

------
jakozaur
Neat!

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

------
xsace
This is what I use: <http://oscarotero.com/jquery/>

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

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

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

~~~
inafield
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.

