Link to demo on each widget page that has one

[jzaefferer]

Picking one idea from #115:

There should be a link to the corresponding demo page on each widget page. It should be styled to stand out. A good spot might be to the right of the page title, somthing like this: (not really this styling, something that looks good).

This would also work for jQuery Mobile. Since the URLs don't have the same scheme, a good option might be to implement an optional attribute or element in the XSLT that gets output as a link, if present. So we'd just add the URL to the demo where it applies.

We should also make the link to the API documentation much easier to spot on our demo pages. The style of both links should probably be the same.

If that sounds good, I can create tickets in the appropriate repos, along with patches.

[scottgonzalez]

I like this idea, but it's confusing that there's a big demo link that doesn't go to the examples on the page. Maybe we should have a single example at the bottom which also links to the full demo section.

[tjvantoll]

I like this idea, but it's confusing that there's a big demo link that doesn't go to the examples on the page. Maybe we should have a single example at the bottom which also links to the full demo section.

I agree that it's confusing to have Examples and Demos links in the same vicinity of the page, but I think having the full demo section link at the bottom of the page hides it too much.

I'll throw out two ideas. With either of these I think @jzaefferer's callout link to the demos makes sense. Let me know what you think.

1. Move the "examples" section to the top of the page, make sure there is only one example that shows the most basic usage of the widget.

The example then serves as an intro to the usage of the widget. The subsequent content shows more customized usage (options, methods, events, etc). If we collapse the source by default it shouldn't take up too much space.

2. Remove the examples from the API docs entirely. The examples are nice when they're integrated into the docs (like some of jQuery mobile's), but in their current location they're kind of hidden anyways.

[jzaefferer]

Both of TJ's suggestions above sound good to me. @scottgonzalez what do you think?

[scottgonzalez]

I like the first suggestion. @jquery/mobile thoughts?

[agcolom]

I'm in favour of the 1st suggestion also. I think it'd be a shame to remove the examples from the API docs entirely.

[arschmitz]

im in favor #1 as well i think it works better for mobile and how our demos work also

[jaspermdegroot]

+1 to @tjvantoll's first suggestion as well.

How are we going to deal with versions? Not only for links from the API docs to the Demos, but also the other way around.

[scottgonzalez]

The entries will have to provide a URL for the demos. That will be managed manually.

[jzaefferer]

Currently the Quicknav links to Examples. Would that go away? Where exactly should the examples get displayed? Before or after Quicknav? Elsewhere? Where would the Demos link go then?

[scottgonzalez]

Currently the Quicknav links to Examples. Would that go away?

I don't think so.

Where exactly should the examples get displayed?

Right after the QuickNav. There would be only one demo.

Where would the Demos link go then?

Right after the example. Likely with some text like "See more demos."

[tjvantoll]

My 2 cents are below.

Currently the Quicknav links to Examples. Would that go away?

Yes. Unless we make "QuickNav" into "Nav" (see below).

Where exactly should the examples get displayed? Before or after Quicknav?

Directly after.

Where would he Demos link go then?

I think what you have here is fine. Or something along the lines of "See more demos" is fine too.

I'll throw out one more idea. I personally would like to see the "QuickNav" just become "Nav" - aka I want the entire outline in there. This solves the "where does the examples link go" problem and gives us a way of linking to anything on the page. For example:

Nav

• Example
• Keyboard Interaction
• Theming
• Dependencies
• Notes
• Options
  • active
  • etc
• Methods
  • destroy
  • etc
• Events
  • active
  • etc
• Extension Points
  • _whatever

[scottgonzalez]

That'll require some design work and updates to all of the entries, but I think that might be a good change.

[scottgonzalez]

@jquery/content @jquery/ui @jquery/mobile Let's revive this and make some progress. Please review the previous discussion and reply with either support for an existing proposal or a new proposal. It's been quite a while since this discussion died down, so I'd like to have people review it before we proceed.

[agcolom]

I think it'd be good to have the basic example(s) that we currently have in the api docs, and they may be more suitable right at the top of the page, probably straight after the description.

We can then remove the examples link in the quick nav and add one for Demos at the top, floated to the right, that links to the widget demo page, possibly in a new tab since this is technically outside of the api docs.

[agcolom]

I think we could also add some links to the top of the page from strategic positions in the api docs page that need to be defined. I'd say add one floated right for each of the option, method and event described so that users can navigate down and up without scrolling.

Alternatively, we could expand on the tree nav on the left hand-side but I'm not sure how practical that would become, as we could end up with a very large number of links and therefore a very large menu that requires a lot of scrolling...

[arschmitz]

I still like the first option above and i also agree with @tjvantoll that the quick nav should be changed to nav and moved to the top anywhere its not. I get annoyed on some of the pages because if i'm looking for a specific option or method i have to scroll a long ways before i even get to the quick nav not super quick, for example http://api.jqueryui.com/jQuery.widget/

[agcolom]

That works too... In that case I think it's still a good idea to bring the "basic" example(s) straight after the nav, so we don't need a link to it. The Demos Link can go either where the Example link is today or at the top...

Here's an illustration with Link to Demos at the top, followed by Nav and examples. I'm finding "Nav" a bit short when we have all this page, and I'd be tempted to change it to something a bit longer... Quick Links? Scroll to ? Navigate to? Jump to?

[scottgonzalez]

i also agree with @tjvantoll that the quick nav should be changed to nav and moved to the top anywhere its not. I get annoyed on some of the pages because if i'm looking for a specific option or method i have to scroll a long ways before i even get to the quick nav not super quick, for example http://api.jqueryui.com/jQuery.widget/

That's actually in opposition to what @tjvantoll said. He wanted the example moved above the nav.

Also, for that specific page, we can't move the nav up because it's not the nav for the page, it's the nav for the second entry on that page. There's already a link at the very top that will take you to the section you want to jump to.

[scottgonzalez]

I'm finding "Nav" a bit short when we have all this page, and I'd be tempted to change it to something a bit longer... Quick Links? Scroll to ? Navigate to? Jump to?

I'm fine with Quick Links, but I'm against anything with "to" in the title.

[jzaefferer]

Also, for that specific page, we can't move the nav up because it's not the nav for the page, it's the nav for the second entry on that page. There's already a link at the very top that will take you to the section you want to jump to.

We could avoid that issue entirely by splitting up that page into two separate entries, with cross links.

I'm fine with Quick Links, but I'm against anything with "to" in the title.

Can we eliminate that element entirely? Something like...

Dialog ----------------------- (Demos)

(widget category)

Open content in an interactive overlay

Options

....

[jzaefferer]

A bit more like a sketch:

[scottgonzalez]

We could avoid that issue entirely by splitting up that page into two separate entries, with cross links.

I suppose if we want to move away from using the actual method/property names for URLs.

Can we eliminate that element entirely?

I think the heading is useful.

[arschmitz]

I think keeping the demo link separate from the nav is going to make people still miss it easily because they look at the nav / links section and don't see it but right below are examples. from a user perspective i would expect the demos link to be within the nav.

[scottgonzalez]

I'll reiterate my original suggestion:

Maybe we should have a single example at the bottom which also links to the full demo section.

That addresses @arschmitz' concern. I don't really care about the location of the example, this concept would work just as well if we move the example above the options.

[arschmitz]

@scottgonzalez that would work for me. The most important thing from my perspective is that people looking for the demos find them quickly and easily i think that would achieve that.

[jzaefferer]

That's certainly an improvement and requires the least changes overall.

[agcolom]

That works for me too, but we need to decide what that link would look like...

[scottgonzalez]

For symmetry with the link from the demos to the API docs, it could just say:

Want to see more examples for the X widget? Check out the demos.

[arschmitz]

Want to see more examples for the X widget? Check out the demos.

Thats exactly what i was going to suggest

[agcolom]

👍

[GSPP]

I'm copying an idea from jquery/jqueryui.com#148:

Changes are marked. Put all important pages on the left and pin them there so that they are visible on all pages.

It is important to show users what pages actually are available. Right now, you can only find other pages if you know they exist.

The navigation should be in the tree/list on the left as the image shows. Navigation links should not be buried in text. Nobody reads all text nor should they.

The following is also relevant to this issue:

An example for good documentation was requested. I think https://simpleinjector.readthedocs.io/en/latest/index.html is really nice. Mainly, because it is so easy to see what documents are available. You don't get lost.