"How jQuery Works" may be misleading

Abierto
  • ¿Algo no está bien?
#658 3 comentarios 0 reacciones 0 asignados Ver en GitHub

@connorcartwright ya está trabajando en esto.

Desde el 10/5/2016.

  • #661 de @lady3bean — cerrado sin fusionar
  • #714 de @connorcartwright — abierto

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
javascript
Área
content, documentation

Línea de trabajo

Comienza revisando los tutoriales “About jQuery” y “How jQuery Works”, junto con los issues relacionados #626 y #641. Aclara con los maintainers la división de los capítulos y la orientación del tutorial interactivo antes de editar. Se considera terminado cuando el contenido de configuración y los fundamentos de jQuery estén claramente separados, con ejemplos mejorados y orientación sobre el orden de los scripts y las prácticas recomendadas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
JavaScript
Estrellas
914
Forks
472
Sin PR fusionados en 30 d

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de jquery/learn.jquery.com

Todos los issues de jquery/learn.jquery.com

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.