Replace JavaScript 101 Section with MDN information using Kuma API

[ajpiano]

As we discussed in #117, maintaining our own JS 101 section adds overhead to our process and is duplicative of the MDN JavaScript and DOM resources. However, straight-up linking to MDN (from where?) without actually having basic JS/DOM content on our site to read at the time was an unappealing prospect. What we did not realise at the time is that there is an API for obtaining the content of MDN and using it elsewhere. This seems like a reasonable, nay... awesome, alternative than hosting and maintaining "our own" JS 101 reference and it seems that it would not be difficult to integrate hitting Kuma into our grunt build.

There are a few kinks to be discussed and ironed out, including but not limited to

• Right now the site can be built offline. Adding Kuma means that would not be possible, or at least it would have to be worked around.
• All of our articles can be contributed-to via Git/GitHub (there's a link to the raw markdown in GitHub on each page) - this wouldn't apply to anything we bring in via Kuma and it could be unclear to folks who want to contribute back.
• All of our articles show contributors by using the git commit history of the file -- again, we'd have to eschew this for content we bring in from MDN
• Anything we'd pull from MDN wouldn't be versioned "by us." Our deploys are automated using git webhooks, and tagging with a semver pushes to the live site. If we use MDN, do we just take whatever we happen to pull from the API at build time and call it a day?

In general, however, this does seem like a generally good idea and I'd like to discuss these sticky points further and then see if we can move forward.

(cc @codepo8)

[lmorchard]

Hi there, I've largely been the author of the code behind the Kuma API. Let me know if you need anything, and I'll see if I can help!

[ajpiano]

Hey @lmorchard, pleased to make your acquaintance! We'll certainly do just that.

[lmorchard]

Also, for what it's worth: We're mulling over a lot of the same kinks you mentioned, for docs in general at MDN & Mozilla. Not saying we have any solutions yet, but interested in more perspectives :)

[groovecoder]

@lmorchard +1 let us know anything you need at dev-mdn@lists.mozilla.org or just file issues at our repos

[DavidBruant]

Just a word about SEO and duplicated content. Search engines, tend to dislike when 2 pages on the web have the same content and in our case may penalize MDN or learn.jquery.com (or both) ranking.
If duplicated content happens, search engines prefer it to happen one of these 2 ways:

• HTTP 301 when possible (we're not in that case since it wouldn't make sense for learn.jquery.com to 301 to MDN)
• have the duplicate page use link@rel=canonical with @href pointing to the url that contains the original content.

Reading/videos on the topic:

• http://googlewebmastercentral.blogspot.fr/2009/02/specify-your-canonical.html
• http://googlewebmastercentral.blogspot.fr/2009/12/handling-legitimate-cross-domain.html
• http://support.google.com/webmasters/bin/answer.py?hl=fr&answer=139394
• http://www.mattcutts.com/blog/rel-canonical-html-head/

[ajpiano]

Thanks for the heads up @DavidBruant - using @rel=canonical and getting it into the head presents a minor challenge, but not an insurmountable one. All jQuery sites use the same header, so we'd just have to seed pages built from MDN data with some metadata we could use to put the canonical url in the head.

[openjck]

Just wanted to add a point about submitting requests for new features you might need. Our Bugzilla form would be an ideal way to do this, assuming you don't mind signing up for an account. The form helps us to understand exactly what you need so that we can provide it as soon as possible.

And if you haven't noticed, we are thrilled to be working with you. Looking forward to seeing where this goes.

[scottgonzalez]

This presents licensing challenges as well. MDN content is CC-BY-SA 2.5, while our content is MIT. MDN code samples are a mixture of MIT and CC-0 while our code samples are CC-0.

[groovecoder]

@teoli2003 may be able to help with how to attribute MDN content in jQuery docs. FWIW dochub.io simply attributes in an About page:

http://dochub.io/#about

[teoli2003]

IANAL, but the explanation there is the one to follow: https://developer.mozilla.org/en-US/docs/MDN/About#Copyrights_and_licenses
Also, dochub.io has an attribution box on each page.

[scottgonzalez]

I understand how we can properly attribute the content properly. I just think it's a very important factor to consider. It complicates the licensing quite a bit, actually. Especially if the content gets stored in the repository and not just hosted on the site.

[arthurvr]

Last comment in here was quite a while ago, so let me re-open this discussion.

We should probably prioritise this issue a little, since we shouldn't maintain a section that will get replaced by other content soon. Currently more than 20 open issues are regarding this section.

[dmethvin]

I would vote to use the power of the <a> and just link to good content on learning JavaScript. Teaching JavaScript seems beyond the scope of this particular site.

[kswedberg]

👍 to @dmethvin's comment

[danheberden]

If we offer tutorials in the "js 101" camp, then great - but as for technical resource and reference, 👍 to linking to MDN

[arthurvr]

@danheberden Currently the articles are more likely structured as reference than tutorials. Except the getting started, but that kind of tutorials are all around the place, so.

---

My suggestion:

• Remove the Javascript 101 section as it is, and replace it with a list of linked handy resources in the right order. That shouldn't be limited to MDN tho.
• On top of that page, include an intro covering what Javascript is and why it's important.
• In the future we can still add real tutorials on raw Javascript.

If you want, I can take that all this week. Keep in mind that would enable us to close a huge bunch of issues.

[dmethvin]

Sounds like a good way to go then! 😈

[kswedberg]

sounds great to me, @arthurvr!

[agcolom]

👍