"How jQuery Works" may be misleading

オープン
  • 何か問題がありますか？
#658 コメント 3 件 リアクション 0 件 担当者 0 名 GitHub で見る

@connorcartwright がすでに取り組んでいます。

2016年5月10日 から。

  • #661 @lady3bean による — マージされずにクローズ
  • #714 @connorcartwright による — オープン

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
25/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
javascript
領域
content, documentation

調査の方向性

まず「About jQuery」と「How jQuery Works」のチュートリアル、および関連する issue #626 と #641 を確認します。編集する前に、maintainers と章の分割およびインタラクティブチュートリアルの方向性を明確にしてください。セットアップと jQuery の基本に関する内容が明確に分離され、スクリプトの順序と推奨されるプラクティスに関する例とガイダンスが改善されていれば完了です。

索引モデルが issue の本文から書いたものです。

説明

Chapter: about GSOC

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.

主要言語
JavaScript
スター
914
フォーク
472
30日以内にマージされた PR はありません

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

jquery/learn.jquery.com のほかの issue

jquery/learn.jquery.com の issue をすべて見る

似ている issue

JavaScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。