"How jQuery Works" may be misleading

Aperta
  • Qualcosa non va?
#658 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

@connorcartwright ci sta già lavorando.

Dal 10/5/2016.

  • #661 di @lady3bean — chiusa senza merge
  • #714 di @connorcartwright — aperta

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
javascript
Ambito
content, documentation

Direzione di ricerca

Inizia esaminando i tutorial “About jQuery” e “How jQuery Works”, insieme alle issue correlate #626 e #641. Chiarisci con i maintainers la suddivisione dei capitoli e la direzione del tutorial interattivo prima di modificare i contenuti. Il lavoro è completato quando i contenuti relativi alla configurazione e alle basi di jQuery sono chiaramente separati, con esempi migliorati e indicazioni sull’ordine degli script e sulle pratiche consigliate.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
JavaScript
Stelle
914
Fork
472
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di jquery/learn.jquery.com

Tutte le issue di jquery/learn.jquery.com

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.