Closed
Description
Below is my initial content review for the $.ajax() section of the learning site. I'll be conducting reviews on more sections soon and posting them so we can discuss/assign writing tasks as needed.
http://stage.learn.jquery.com/ajax/
- Needs to be significantly more extensive. Currently only scrapes the surface.
- What is ajax? (more complete technical explanation). I don't think we're properly explaining just how much it can change how a developer looks at the flow of data in an application. Remember that we're talking about educating beginners (and later tackling advanced userS). More questions to address: why would I want to use Ajax? How does it help me?
- What's the problem with implementing Ajax without jQuery? Why is it more painful? (to a newcomer, a code snippet for how to implement this cross-browser vs using jQuery could perhaps be shown). This would definitely help them appreciate the benefits of abstraction.
http://stage.learn.jquery.com/ajax/key-concepts/
- Where are all the examples?
$.get()? $ .post()? etc. A lot of methods are mentioned but as a beginner I would hope to see examples too. This is where we need to either move over examples currently in the API docs or form a bridge between both resources. - I would expect/hope to see tutorials here - either in a separate entry or in key concepts. Based on what we have, a reader would appreciate that $.ajax() does a lot, but I think this is where we should be educating them further.
- Consider covering typical tasks (some of which the API docs do): how do I consume a JSON data feed from an external/local source? worth showing a twitter API example? xml for those still using it?
- We currently don't have a mention of deferreds at all. 6 months ago I would have said it's considered a more advanced topic, but given just how much power it has to improve the way people approach XHR, should this also be covered here?
http://stage.learn.jquery.com/ajax/jquery-ajax-methods/
- Again we have nowhere near enough examples. We mention lots of options - perhaps it would be useful going through how to use them?. Don't have to cover everything but give people some snippets to help them 'grok' how it all fits together
- I think we need to decide how much we rely on the API docs site for our examples. Right now we're trying to push people to look there for examples and narrative (via links), but I think the docs site should cover a) how to use methods, b) gotchas with perhaps some more of the narrative being in the learning site. Thoughts?
http://stage.learn.jquery.com/ajax/ajax-and-forms/
- Right now we're really not covering the fundamentals of how Ajax works with forms. Traditional form handling vs the new. $.ajax has the power to greatly change everything from validation (e.g 'sorry, your username is taken') through to prefiltering but we've giving a very very minor summary of what is possible. I think we need to somehow address this. A first attempt might at least bring over more examples from the docs.
- Locate articles that cover this well and see if we can borrow from them. As per the other sections, I do not think we want to end up in another situation (as with the old site) where we're linking to articles that end up outdated with time, so borrow or write this out ourselves.
http://stage.learn.jquery.com/ajax/ajax-events/
This is another example of where pulling in examples we have in the API site would really help. Even if we were to just take out the code snippets from http://docs.jquery.com/Ajax_Events and add a lot more narrative around them to explain things that would be better than what we have right now.