Better Index Page

[scottgonzalez]

The index page should provide an overview of the docs, mention which version the docs apply to, where to find older versions, link to intro tutorials on the learn site, etc.

[timmywil]

Scott and I disagree on this. I've always liked that api.jquery.com goes straight to docs. Skip the useless intro. I don't think we need to say which version the docs apply to. They apply to the current version. If it's behind, it's a bug. We update docs before releases. All versions are listed on the page in the sidenav. And it seems to me the learn site (and therefore its tutorials) can stay separate.

[ajpiano]

I don't think the intro is "useless" -- clearly there are a few things that need to be commonly pointed out to consumers of the API docs, and there are ultimately plans for versioned docs, because it's a pain point we hear about often. A major reason the learn site and try.jquery.com exist is because people come to the API docs expecting to "learn how to use jQuery" but it really isn't that at all....it's just a listing of methods... we should point those people to the right place and explain that they aren't there yet. Not sure why we would want to keep those things "separate."

On the other hand, there is something really convenient about having the full method listing available for quick Cmd-F'ing and finding the method you're looking for docs on. A lot of other open source js libs do this by having the full method listing as navigation on the left hand side (instead we have categories, which are of dubious utility IMHO). Indeed, we could probably keep the full method listing on the home page and just put the basic "who what and where" information above it, similar to Underscore.js.

Best of both worlds?

[kswedberg]

+1 to having a brief intro above the listing on the homepage. What do y'all think about #227 and #228?

[timmywil]

Ok, maybe I was just thinking about how I use the docs site. But I think Adam's solution is great.

[timmywil]

Also, @kswedberg, I completely agree restoring those conveniences would be great. If I could get the time, I'd submit a pull myself.

[timmywil]

woops tricky mouses.

[dmethvin]

What is the action on this? Just a short summary at the top of our current home page? Given that this is the API reference I don't think we need links to tutorials or or other topics like plugins.

[scottgonzalez]

I think something similar to http://api.jqueryui.com/ would be good.

Some things that would be useful:

• Links to the changelogs and upgrade guides.
• Links for beginners that point to learn.jquery.com and try.jquery.com.
• Links to other API sites (UI, Mobile, but just the home pages, not a list of each versioned site).

There's clearly still debate about whether there should be a massive dump on the home page. I still think linking to a separate page (http://api.jquery.com/category/all/) is better (BTW, we need to figure out why that page is broken now - it's broken on all of our API sites).

[scottgonzalez]

I created jquery/jquery-wp-content#278 to track the /category/all problem.