The click entry contains an image instead of an example #829

Open
mgol opened this Issue Nov 10, 2015 · 7 comments

Comments

Projects
None yet
4 participants
@mgol
Member

mgol commented Nov 10, 2015

The click entry contains an image instead of the first example which makes the example broken.

@arthurvr

This comment has been minimized.

Show comment
Hide comment
@arthurvr

arthurvr Nov 10, 2015

Member

Sure, let's make the example actually usable. Nice catch. 👍

Member

arthurvr commented Nov 10, 2015

Sure, let's make the example actually usable. Nice catch. 👍

@agcolom

This comment has been minimized.

Show comment
Hide comment
@agcolom

agcolom Nov 11, 2015

Member

This is the case for all the examples on api.jquery.com (see http://api.jquery.com/dblclick/, http://api.jquery.com/fadeIn/, http://api.jquery.com/fadeOut/, etc). On this repo, only the generated examples (after the Example: heading) are working examples. I agree that it would be nice to have these examples "working", as the images can lead to confusion for the user. We need to decide which strategy to adopt for this. I believe that as we have the long "working examples" with generated iframes at the bottom, we would want to only show the brief code examples here (not the full code). Should we go for a small manually added iframe here for these smaller demos or modify the xslt to be able to generate these? This can be tricky as we do not want to show all the code, just a small part. For api.jquerymobile.com, all the small examples are manually added iframes. It's not been a problem for me to update them as and when needed. In addition, the manually added iframes mean that the user can see the source code, so if we went for the generated iframe solution, we would possibly have to also add a way for the user to see the source (as the code shown on the page would only be a small portion for improved readability, as we currently do). I am open suggestions as to how best achieve this. I believe that there are not that many examples throughout...

Member

agcolom commented Nov 11, 2015

This is the case for all the examples on api.jquery.com (see http://api.jquery.com/dblclick/, http://api.jquery.com/fadeIn/, http://api.jquery.com/fadeOut/, etc). On this repo, only the generated examples (after the Example: heading) are working examples. I agree that it would be nice to have these examples "working", as the images can lead to confusion for the user. We need to decide which strategy to adopt for this. I believe that as we have the long "working examples" with generated iframes at the bottom, we would want to only show the brief code examples here (not the full code). Should we go for a small manually added iframe here for these smaller demos or modify the xslt to be able to generate these? This can be tricky as we do not want to show all the code, just a small part. For api.jquerymobile.com, all the small examples are manually added iframes. It's not been a problem for me to update them as and when needed. In addition, the manually added iframes mean that the user can see the source code, so if we went for the generated iframe solution, we would possibly have to also add a way for the user to see the source (as the code shown on the page would only be a small portion for improved readability, as we currently do). I am open suggestions as to how best achieve this. I believe that there are not that many examples throughout...

@kswedberg

This comment has been minimized.

Show comment
Hide comment
@kswedberg

kswedberg Nov 11, 2015

Member

For historical background, the entries have "code + image" within the description because they were originally taken from my book, which, being made of paper and not subject to the magic of Hogwarts, couldn't display dynamic examples.

One thing to consider is that the api documentation has been consumed by a lot of other apps and documentation sites. What would be the effect on third-party use of the documentation if we pulled the code + images?

Member

kswedberg commented Nov 11, 2015

For historical background, the entries have "code + image" within the description because they were originally taken from my book, which, being made of paper and not subject to the magic of Hogwarts, couldn't display dynamic examples.

One thing to consider is that the api documentation has been consumed by a lot of other apps and documentation sites. What would be the effect on third-party use of the documentation if we pulled the code + images?

@agcolom

This comment has been minimized.

Show comment
Hide comment
@agcolom

agcolom Nov 11, 2015

Member

I'd like to keep the code and images and add the corresponding working example.

Member

agcolom commented Nov 11, 2015

I'd like to keep the code and images and add the corresponding working example.

@mgol

This comment has been minimized.

Show comment
Hide comment
@mgol

mgol Nov 11, 2015

Member

When I was trying to get jQuery upgraded on the API sites I was clicking over the various pages and it was very surprising to me that clicking on the box didn't work. I thought the update just broke it so I checked the original and thought it's broken as well. Only after inspecting the source I realized it's an image.

A book is different in that no one expects it to be interactive, it's natural for people to just see how it looks. In the web most people would expect examples to be working according to the examples so I think if we keep images it will always be confusing.

I think if those images were replaced by small iframes with the code mentioned above it would be more natural for people. I agree we wouldn't want full HTML code in such small introductory snippets so manually added iframes seem fine for me. But once those iframes are in I don't see much value in keeping the images.

Member

mgol commented Nov 11, 2015

When I was trying to get jQuery upgraded on the API sites I was clicking over the various pages and it was very surprising to me that clicking on the box didn't work. I thought the update just broke it so I checked the original and thought it's broken as well. Only after inspecting the source I realized it's an image.

A book is different in that no one expects it to be interactive, it's natural for people to just see how it looks. In the web most people would expect examples to be working according to the examples so I think if we keep images it will always be confusing.

I think if those images were replaced by small iframes with the code mentioned above it would be more natural for people. I agree we wouldn't want full HTML code in such small introductory snippets so manually added iframes seem fine for me. But once those iframes are in I don't see much value in keeping the images.

@kswedberg

This comment has been minimized.

Show comment
Hide comment
@kswedberg

kswedberg Nov 11, 2015

Member

@mzgol : I absolutely agree that people's expectations are different depending on the medium. I was only providing historical background for why the images are in there in the first place. Still not sure, though, what kind of effect it would have on third-party documentation.

Also, seems like a pretty big task to update all of them to working examples, but if someone is up to the challenge, go for it. As an alternative, you could just wrap those images in a <figure> tag and add a <figcaption>. Less desirable, but probably less work.

Member

kswedberg commented Nov 11, 2015

@mzgol : I absolutely agree that people's expectations are different depending on the medium. I was only providing historical background for why the images are in there in the first place. Still not sure, though, what kind of effect it would have on third-party documentation.

Also, seems like a pretty big task to update all of them to working examples, but if someone is up to the challenge, go for it. As an alternative, you could just wrap those images in a <figure> tag and add a <figcaption>. Less desirable, but probably less work.

@mgol

This comment has been minimized.

Show comment
Hide comment
@mgol

mgol Nov 11, 2015

Member

Also, seems like a pretty big task to update all of them to working examples, but if someone is up to the challenge, go for it.

Yeah, I described the ideal which might not be achievable soon. :-)

As an alternative, you could just wrap those images in a

tag and add a . Less desirable, but probably less work.

I like it! The examples would still not work but it'd be obvious they're just images so I (& perhaps others) wouldn't be so confused about why clicking does nothing.

Member

mgol commented Nov 11, 2015

Also, seems like a pretty big task to update all of them to working examples, but if someone is up to the challenge, go for it.

Yeah, I described the ideal which might not be achievable soon. :-)

As an alternative, you could just wrap those images in a

tag and add a . Less desirable, but probably less work.

I like it! The examples would still not work but it'd be obvious they're just images so I (& perhaps others) wouldn't be so confused about why clicking does nothing.

@kswedberg kswedberg referenced this issue in jquery/jquery-wp-content Dec 2, 2015

Closed

Styles for figure/figcaption on api.jquery.com #383

kswedberg added a commit to jquery/jquery-wp-content that referenced this issue Dec 2, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment