Content discussion

[addyosmani]

The learning site needs to be an authoritative source of information for learning most of the common tasks developers use jQuery for. I believe that's the end goal we're after with this project. Right now, however, although the content we have sat well in the context of jQuery Fundamentals, it is no-where near comprehensive enough to match what our goals are with the site. (we're finding this as we read through the sections again - see #38 for one example)

It came up in a recent call, but I'd like to discuss just how much the API docs might influence the content in the learning site. Over time, the quantity of narrative we've seen go into the API docs has increased and I believe it might be of mutual benefit to discuss how we can both tackle our problem of content (and help avoid overflow in the docs site at the same time).

For example, I would expect the API docs to cover detailed information about methods, a few examples and of course, gotchas. Beyond that perhaps any narrative that seeks to teach developers how to use a feature (including code snippets, tutorials etc) should perhaps be in the learning site. We can then cross-reference content to avoid a significant amount of duplication and ensure users have a clear path of where to a) learn about a feature and b) get API reference for it.

We can (and will) of course probably continue to seek the integration of well written blog posts about API features the learning site covers in there, but when it comes to features like say..$.ajax(), I've seen nothing as comprehensive as what we have in the API docs at the moment. If we feel that it would make more sense for the learning site to merely be an introduction to features, that's fine too, but it would be useful for us to get a consensus.

Adam mentioned us someday covering building serious applications with jQuery and if/where it fits in there and in that respect, I guess the learning site might become something like our own MDN. It would be great to hear from others about their thoughts on what the learning site should be (content wise) and where it might (or should) sit with respect to the API docs site.

//cc @ajpiano @danheberden @dmethvin @kswedberg

[danheberden]

I think there's a line between palatable and comprehensive that needs to be drawn at least in this initial phase. Nothing should be as comprehensive as the $.ajax entry on the api site, as it's goal is to cover every available configuration option.

I would like to see, however, the two integrated in a sensible manner. On the $.ajax page, it would be great to have some links to ajax 101, using deferreds, and dealing with SOP.

The API site should always be the meat of jQuery; it has to be. In covering every option, though, it has to be very focused. The learning site is free to focus on a tangent, create a recipe of methods and practices, and encourage things like proper debugging, unit tests, and revision control.

I suppose when it comes down to it, the distinction would be that the api site should cover one method at a time. The learning site should teach using that method in context with other methods and scenarios.

Hope this makes sense and hope i understood the question/issue correctly :)

[dmethvin]

I do like the idea of having cross-references from the api site to the learn site. It would be great to have the prescriptive advice and examples that put together several apis done at the learning site.

As I've been looking at how people use jQuery I've come up with a few ideas for articles which I'll be happy to do--once I can remember them again. It would also be great to show where it's better to add something like Backbone, once the code gets to that "certain size" where some simple DOM event handlers ain't cuttin it. The emphasis should still be on jQuery, but even showing people the limits is an important public service.

[ethransom]

I feel that since we already have the API for comprehensive and complete coverage, the learning site should be centered more on real life applications and tutorials. Consider this: for a large portion of my jQuery career, I considered myself competent with it. I read the API, and could cook up some pretty good apps if I wanted too. However, I didn't even know about live() until I read a book that had real life coding projects.

Example code is great, but the API already has that covered. I would like to have the website more tutorial oriented.

[addyosmani]

Thanks for the feedback @danheberden, @dmethvin and @Schnauzer! So, effectively it looks like we want the learning site content to offer something between tutorials and recipes for how to use jQuery features, but nothing as comprehensive as the API in terms of it's goals when it comes to detail. That makes sense.

This will certainly help guide some of the work we have to do to get the content in shape. I was concerned we wanted to demonstrate recipes for most popular methods, but perhaps we should set our sights on covering common tasks and build it up to be more advanced from there. Areas like the $.ajax section could certainly use this treatment.

[addyosmani]

Soo..

Related to the content discussion:

I spoke to Scott about the current progress on the other site refreshes and although we do still have time to get the content sorted out for this project, I'd like to increase the pace at which we improve what we have at the moment.

Timewise, I'm able to commit to content/technical review (but not much more for the next few weeks).

To help keep things chugging along however, I'm going to try bringing a few more people in with technical writing experience to review the areas we've identified as lacking as submit PRs to help get them in shape. I'll be reviewing anything they submit (and please feel free to as well).

End goal is to just make sure we're happy with what we're putting out there roughly within the release timelines for the other projects.

[Jakobud]

Just checking out the project. Wanted to chime in on this. Looking at the following page as an example:

http://stage.learn.jquery.com/ajax/jquery-ajax-methods/

In my opinion, this page is definitely NOT the place to be listing out and describing every single $.ajax option. That belongs in the API. The page should show a basic code example on how to use $.ajax() and then briefly describe all the options used and then have a link to the API docs, making it clear that there are more options that are more thoroughly explained in the docs.

[ajpiano]

Agreed, that page is definitely an odd duck. We don't need to dupliate the API reference, but we probably do what to tell the stories of how those dfferent options can work together to solve common problems.

[dmethvin]

The basic problem with a single page for $.ajax is that it has a very complex API. I agree that some sort of simple recipes for common problems is the best way to go here. Perhaps break out into different pages to handle common situations like JSONP where many of the XHR-related features are moot.

[ajpiano]

I think we have a much clearer idea at this point what the learn site's mission is. I've created #180 to track progress of the more specific issue of removing API-doc-eesque content.