Rethink widget docs

[jzaefferer]

Our API pages are huge, listing everything on a single long page. Demos are separate on a page on the main site (not the api subdomain). Some users report having to switch a lot between these two pages for a given widget, e.g. http://jqueryui.com/autocomplete/ and http://api.jqueryui.com/autocomplete/

We'd like to improve this, but don't yet have any idea how. Looking for input!

[rdworth]

We might want to take another look at some other projects and find what works better, if we can find anything. @scottgonzalez and I did this 6 months ago or so, maybe 9. It was painful, because as much as ours can be improved, there are lots that are much worse. But we can find some gems and gets some ideas.

[agcolom]

How about having a switch a bit like this: http://jsbin.com/amodut/2/ next to the widget name at the top of the pages (on the widget api doc page and the widget demo page), aligned to the right, to easily switch between the api docs and the demo for that particular widget? (obviously restyled to match the look and feel of the project... and possibly resized?)

[jzaefferer]

From the survey: "I very much like the idea of a reduced demo that only shows a very specific aspect of the API and a "real world" demo similar to what has already been discussed as a composite demo."

This is something we discussed before - have the API documentation embed executable demos (not just sample code, as we have now), and potentially more than one per API aspect. Then make the demos actual demos, not the API walkthrough that they are now, for the most part.

[twhitmorenz]

Hey Jörn, Richard, Anne-Gaelle --

I raised a couple of issues about the UI Docs myself, concerned with readability/ scannability of the listings, and loss of depth (things like Tabs, preventing FOUC).

#122
#121

Both of these were closed a bit quickly, I think -- not actually solved, despite being genuine issues & improvement being possible. Perhaps we should consider these a bit further.

Perhaps we need a switch between 'Width Demo', 'API', and 'Usage Notes'? With better sectioning & visibility of the API sections?

Thanks people.

[scottgonzalez]

We've been "looking for input" for nine months now. Either we'll come up with better ideas or we won't, but having this issue open has clearly not helped.