PromoteJS – A Worldwide Call For Improving JS Documentation Visibility

This is a guest blog post by Chris Williams, the curator of JSConf. We are proud to support the PromoteJS campaign and hope everyone will join us to improve JS docs and make the MDN a better place for all web developers.

PromoteJS – A Worldwide Call For Improving JS Documentation Visibility

JS is not a toy language. That reality is just now reaching most developers and their first impression of JS is absolutely abysmal. Do you know what shows up when you search for “JavaScript“? The search engine results page is topped by a Wikipedia article which is shortly followed by the page for downloading Java. This is probably why so many people still unfortunately believe there is a connection between JavaScript and Java. The results for other common search terms like “Learn JS” and “JS Array” is equally as bad if not worse.

JS Guide

This is the first impression of JS by the general masses who are coming to this language and once you see this, you can see why people consider it a “toy language” and understand how so much bad code and disdain can exist for JS. We have hidden the better tutorials, learnings, and documentations away from ourselves AND more to the point, those trying to learn this language. New entrants struggle to learn JS, but eventually just adopt what they know from PHP, Java, Perl, Python and Ruby to a close approximation of runnable code that suffices. They then publish it back out, proud of what they have done, and continue to perpetuate this plague of improper JS coding.

We have failed our fellow designers AND developers in this sense. We have made it almost impossible to learn proper JS, a language with both beauty and warts. Some will say it is not our fault, that browser vendors should provide the API documentation for the implementation or that the standards committee should publish and market it. I am calling bullshit on that. I say that it is up to us to invite, welcome, and most importantly properly educate people looking to learn JS. We, the best and brightest of the field, have an obligation to help those who are trying to learn and understand the complexities of the language. We are the ones that benefit from it most, since those now entering the language will be either extending, morphing, or taking over the very projects we are just now starting. Regardless of library, framework, and even language — if everyone knows how to program proper JS a little better, we all win. Period.

So I challenge you to put down your library or framework preferences and write about some interesting facet about the JS language. Describe how you find the attributes on an object, what the difference between an object and an array is (and how to tell the two a part), anything and everything. If you seek fame and click traffic, write about the entry level stuff. If you seek respect and deep dialogs, write about the difference between implementations and convey the wisdom of when to favor one method over the other. If writing is too time consuming or your muse escapes you, I am announcing today a new campaign, PromoteJS. Through organic guerrilla SEO we can change how search engines present answers to common queries about our language and in doing so improve the visibility of proper educational resources. Our initial target for PromoteJS is to make the proper MDN documentation the first result for standard new JS developer queries.

In order to track our efforts, we have also released Are We First Yet which is a node.js application that tracks the search engine page rank for each of the target terms. Tracking is done on a day-over-day basis so that everyone can see the progress we have made and, if so desired to help the cause, write articles targeting the keywords. With these two efforts, we hope to enabled not just the JS community, but all developers, to improve the visibility of proper documentation. In the few days since unveiling this effort at JSConf EU, there have been millions of page views for the PromoteJS site and the button has spread like wildfire throughout the community. We have already drastically improved the rankings for key terms like “Learn JS”, “Learn JavaScript”, and “JS Documentation”, but we need your help to continue to improve all the rankings.

We need to be the voice of education for our community. We need to promote the proper way of doing things, instead of just ignoring those that don’t “get it” or watering things down. We need to commit to educating our fellow developers on JS, the language, and in doing so it helps all of our frameworks, libraries, meetups, and conferences. PromoteJS is a step in that direction, but by no means the end of the story, be sure to check the site frequently as we continue to add new ways to help improve documentation visibility and the documentation itself.

Chris Williams
Curator, JSConf

About Chris Williams

Chris Williams (@voodootikigod) is the Curator of JSConf US and Vice President of Development at OurParents. Much to the chagrin of his wife, he constantly has numerous side projects on-going including: JSConf Live, A Minute With Brendan, and Node SerialPort. All in all he is just trying to get by, nothing more nothing less.

More articles by Chris Williams…

About Jay Patel

I strive to make the web better by making sure those that develop and drive it are happy campers.

More articles by Jay Patel…


  1. Tim Niiler

    There is actually surprisingly good documentation at When I can’t easily find something at MDC I generally check there.

    October 13th, 2010 at 03:51

  2. skierpage

    I’ll keep sayin’, MDN needs interactive documentation with code fragments that you click to edit sample code and then immediately run and see changes. That would reflect the read/write, participatory, and FUN nature of the web. The writing on most of the site is **fantastic** especially core JS, but I’d rather go to a lesser site where I can type stuff in and play with the samples.

    I tried with the Firefox 4 Tools > Web Console open, as a poor man’s interactive learning environment. var a = 7 returns “undefined”, any trailing // comment you paste in gives bizarre errors, and print(“The value of a is ” + a); brings up the Print dialog! Back to’s poor non-Bespin Try It editor and trying to remember some domain-specific JS/DHTML/CSS/canvas/SVG sandbox tutorial site I played with a year ago.

    October 13th, 2010 at 04:08

  3. David Boswell

    There’s a lot of old JS documentation on that still gets traffic and shows up in search rankings. For instance:

    This shows up first on Google for a search for ‘JS tests’, gets about 20 visits a day and was last updated in 2006.

    Migrating these old docs would increase traffic to the current docs and would remove these outdated docs from the search rankings. If there’s interest in migrating this content, let’s coordinate on the following bug:


    October 13th, 2010 at 10:47

  4. Snap

    Big THANK YOU to you two :-) !
    This is a great idea. I often need to write JS, and I often get confused if not with Gecko, with another browser implementation. So I tried to look at “official doc”. I got some PDFs from ECMAScript. That’s not exactly what one would expect.

    I think we need better global doc, but also:
    – a page that explains implementation differences between browsers, as quirksmode do
    – a page that summarize common pitfalls
    – somewhere to share good code snipets. Not a sourceforge clone, but very common things that would fill in the weaknesses of the language. It would be interesting to analyze javascript frameworks “toolkit” codes for DOM manipulation, CSS selectors, error handling.

    For the basis, Brendan Eich (the JS author) wrote the JS 1.1 specs at . Wikipedia may help, too: .

    I would be glad to share my findings on the wiki, but I would appreciate if someone more experienced could check what I say. I went on the PromoteJS website, it’s a bit disappointing -just a banner. I thought there would be something for contributors to communicate: a forum, irc channel.

    See you on ircs://moznet/js

    October 20th, 2010 at 14:51

  5. Chris Wiliams

    @snap please check the site again, we updated with some information that you might find handy. Thank you for the suggestions.

    October 22nd, 2010 at 08:00

  6. fossbug

    I’ve found this to be one of the best tutorials for JS. It even has a built in console for you to try stuff. Way better than using a dead tree:

    Specifically the online version:

    It’s gentle enough that I’d recommend it for any beginner. Might be a little long-winded for seasoned coders, though.

    October 28th, 2010 at 04:39

  7. skierpage

    @fossbug, that Eloquent JS built-in editor is simple and seems to require minimum changes to HTML pages to make class=”code” editable and runnable with a click. MDNers should check it out! It credits , “/* In-browser code editing made bearable */” , which lists a bunch of other sites that use it.

    October 28th, 2010 at 16:47

  8. ren1999

    Those promoting and teaching JavaScript are doing a very poor job. They do a lot of assuming that people asking questions know more than they really do about implementing JavaScript.

    What we need are full and completely simplified JavaScript examples that you can cut and paste from html to html tag and try for yourself. And Firefox should start a library of these examples.

    My site uses a lot of new JavaScript techniques that hardly anyone is using and they should.

    Now here is a guy that is using JavaScript in ways not many people know are possible. He’s doing it with alert boxes but I think that the Firefox JavaScript group should take this program and create long lists of full html to html tag examples of best practices.

    I still don’t know what the best way is to capture an input value, store it in an array and display that value in different forms with the same Ids is. I asked for months but never got straight answers.

    It would be quite easy for us to promote Firefox JavaScript programing fun. We’ve just got to have people and sites that are friendly and know how to socially teach with full html to html tag examples.

    If anybody knows some best practices for making this CombatTracker JavaScript program better without alert boxes, please email me.

    February 4th, 2011 at 09:13

Comments are closed for this article.