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...
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?
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.
@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.
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.
jquery
