"How jQuery Works" may be misleading

首先查看“About jQuery”和“How jQuery Works”教程，以及相关 issue #626 和 #641。在编辑之前，与 maintainers 明确章节划分和交互式教程的方向。完成的标准是：设置内容与 jQuery 基础内容清晰分开，并改进示例以及有关脚本顺序和首选实践的指导。

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.