"How jQuery Works" may be misleading

[lady3bean]

In the process of learn site review, #626

I’d like to propose some changes to the tutorial under “About jQuery”. When I first read from the jQuery documentation, I got tripped up a bit because I expected “About jQuery” to be an abstract description of the organization and the library, and “How jQuery Works” to be about the inner workings of jQuery. I therefore skipped this section, until I finally found my way back to it because I wasn’t seeing a tutorial for something more practical: “How to Setup jQuery”.

Setup seems like the first step, and then from there you can go into the basics, not so much of how jQuery works, but the basics of “How to Use jQuery”. Not only is the chapter title inaccurate, but as a fix I would like to propose splitting the chapter up into two sections that would be more specific and easier to navigate to.

“How to Setup jQuery” would be useful for folks who need that snippet of information so they can get back to playing with the library -- maybe you’re already familiar with jQuery but have never worked on a project where you’ve had to add it in yourself, or you don’t know whether you should download it and serve it up or source it from another server. It’s also possible to fit this info into one page, making it a quick reference point.

The fundamental uses of jQuery that are covered in “How jQuery Works” could then be split up into an overview of jQuery basics, which, I think, similarly constitutes its own zone of interest for people who may not need to read the setup part anyway. With more direct labels -- perhaps they could be labeled as tutorials as well -- you’d be able to more easily find what you’re looking for.

Furthermore, both of these subjects can be covered in clearer words and better depth. Especially for the setup information, I’m not sure it’s worth the instant gratification to suggest including js code within the html. Since you’re not walked through an example with a separate js file, ultimately we’re not demonstrating the way that is preferable for using jQuery or, for that matter, any javascript code. This principle of the separation of content, action, and presentation is worth including and the main example should demonstrate this. Besides, we’re already loading in jQuery as script source -- is bringing in the javascript file this way that much more work? Since we’re talking about document ready-ness here too, this seems like the perfect place to explain the order in which you need to bring in your scripts and dependencies. Though there is a warning against the script tags, it’s too far down on the page to be immediately recognized, and this same problem pops up again where it talks about the onload function before explaining that that’s not the preferred way to do it. At a glance, both of these frowned-upon practices seem to be the focus of the tutorial, and that just seems wrong for a first impression. There’s an opportunity here to set people on the right track and introduce some general knowledge of how to bring in responsive components to otherwise static websites. I realize that the idea here is to get people up and running with jQuery, but part of my hope in splitting up the chapters is to let the setup information be a solid reference on its own, so it wouldn’t be too much at once as beginner documentation.

Unless anyone objects to this chapter splitting or to the particulars of the content of the articles that I’ve brought up, I was thinking of tackling this soon and will offer my proposed changes. I have also been keeping in mind the call for interactive tutorials, #641, and was thinking this content is ripe for something interactive, and I think it would be super fun to use jQuery in order to explain jQuery! However, I’m not sure where y’all are on that and if any decision has been made as to the framework or templating for such tutorials. I’d be hesitant to start hacking away at one without some guidance on how you’re envisioning integrating these tutorials onto the learn site (or somewhere else, whatever the case may be). Any feedback or alternative suggestions would, of course, be welcome.

[agcolom]

@lady3bean I very much like your proposals and look forward to your PRs. We had a discussion last week, and we would definitely want to use best practice and applied coding standards in both the documentation and learn sites.

With regards to the interactive tutorials, we've not made much progress at all further than initial thoughts. It was pointed out by @scottgonzalez that Koans would be a good way forward and we also received recommendations not to rely on additional infrastructure maintenance. In addition, we do not want to lose all the existing content, and with the current articles, we could simply look at adding small entries for users to test their understanding to the current learn site, so for example, where we have http://learn.jquery.com/jquery-ui/getting-started/#jquery-ui-basics-using-options we could add something like http://jsbin.com/gofirumecu/1/edit?html,js,output so we would not have a new infrastructure. The testing of the correctness of the proposed solution by the user could be done using qunit (as in the given example).

With that in mind, @arschmitz and @arthurvr started to work on a demonstrator:
https://github.com/arschmitz/jquery-tutorials
and
https://github.com/arthurvr/jquery-tutorials

This summarises where we are with interactive tutorials. I'd like it to be as easy as possible for users to "try out" and test their knowledge, and look forward to further discussion/proposals on the subject.

@arschmitz @arthurvr @scottgonzalez please feel free to add comments you may have on the subject.

[connorcartwright]

Hey @agcolom

It looks like the pull request was never finished or approved - shall I continue where it left off in a new request?

[agcolom]

@connorcartwright yes, that's probably a good idea. thanks!