improve documentation readability

[wookiehangover]

I was really surprised to discover how much fail went into the re-organized docs section of the new qunitjs site. Major, major step backwards in my opinion.

Here's what needs to be fixed, since these are all regressions from the old docs that seriously detract from readability:

• method names should also show method arity the expected arguments - presently, instead of being shown a quick-to-read and helpful list of all methods and their expected arguments, the user is presented just the raw names of the API methods, with a short description of them. Any clue as to what arguments a method takes is trapped behind a click and a page load.
• category groupings should be shown at the documentation root. At first I didn't even notice that the categories are listed in the right column, but then the category names where unfamiliar and confusing. I understand the purpose of giving each category its own page and url, but unless live-search is implemented (like on api.jquery.com), index of the documentation section is a barrier to entry for users both new and old.
• ordering should be logical, not alphabetical. On the jQuery.com QUnit docs, all APIs are grouped by their functional grouping, and are presented in a, err, logical order rather than an alphabetical one.
• whitespace, just look at all that whitespace. I'll gripe about the fontsize later, but just take a good, hard look at how much whitespace is on that alphabetized docs page. The previous docs page let you view at least 14 or 15 methods at at time on a decent sized monitor. The current docs page limits you to a scant 5!

These are just nice-to-haves:

• why is the font for API methods 22px?
• category names provide less insight into what their APIs do -- granted this is a bit subjective, but feel like the "Testing," "Assertion," and "Async Testing" categories provide much more insight that the current arrangement, but again that's debatable
• less green, this whole things looks like its Kermit the Frog's last colonoscopy video
• can the whole design just be simplified? Take a quick look at 2 other popular test frameworks documentation sites, Mocha and Jasmine. Now, I know that design is entirely subjective, but what strikes me is that Qunitjs.com has problems with clutter, organization and lack of clarity. To get any useful information, you're a minimum of 2 clicks before getting at it. Given that its a testing framework with a relatively small surface area, is that really necessary? Couldn't the same set of problems be solved by a simple, uncluttered landing page that lists all API methods and a few examples of simple qunit tests to give them an overview on why QUnit is awesome (and why oh why do you lead off with HTML test setup? Is that the most relavant information for someone new to QUnit? absolutely not. show them tests. show them how easy qunit is. don't show them an HTML document as the first point of entry. /rant ).

Here's a quick demonstration of all these regressions working together in terror, vs the old, beloved docs site:

At least this was succinct...

[cowboy]

FWIW, I basically missed the grey left-nav in the docs until just now.

+1

[nimbupani]

[Update] @wookiehangover points out it is already mentioned as #16. Sorry.

[wookiehangover]

@nimbupani see #16 :)

[danheberden]

Side note: the actual functionality of the theme and layout of this site is very much beta; we actually were trying to not call attention to it because we've been working on updating all of the other jQuery properties. @wookiehangover thanks for the feedback, i'm sure that will help on more than just this site as for the navigation and flow of things is concerned.

[rwaldron]

It's a public repo—feel free to "Talk less, Do more"

[danheberden]

Also, the actual theme stuff is here: https://github.com/jquery/web-base-template

[wookiehangover]

@danheberden RE: not calling attention to it

why is there a big nasty deprecation warning on http://docs.jquery.com/QUnit if this is still beta-ish?

[danheberden]

Cuz we were kinda stuck in a weird place - all the new docs were on qunitjs, but the design wasn't done yet :/

[scottgonzalez]

method names should also show method arity

Fixed in jquery/api.qunitjs.com@99ec5c06040c3c6f689d4f75924a7fb8b55e2418

category groupings should be shown at the documentation root

Fixed in jquery/web-base-template@c473ebf

ordering should be logical, not alphabetical

That's just not going to happen. The QUnit API site will function the same as all jQuery API sites. A tutorial would be better for what you want.

whitespace, just look at all that whitespace

The design for the API sites haven't been fleshed out or implemented yet. As @danheberden has pointed out, qunitjs.com launched early, the final designs will come soon.

Feel free to open new issues for any remaining individual bugs/features. This site is still very much a work in progress, but we'll need more granular issues (and not ones that say "redesign the whole site").

[wookiehangover]

@scottgonzalez thanks for the feedback.

I'll avoid trolling you guys with a "redesign the whole site" ticket in the future :feelsgood: