The timing of Promote JS! is impressive. Just last Friday, I was complaining to one of my colleagues about the decrepit state of online JavaScript documentation, as viewed through the lens of the major search engines.

It turns out that the search engines actually do a fine job for most languages:

• “php string” — Google’s top result is the PHP String Functions section of the official PHP.net manual, with PHP Strings as a secondary result. I actually might flip the order here, but still an excellent job. Bing points directly to the string page, with a bunch of secondary links. Also excellent.
• “python string” — Google’s top result is the Built-in Types section of the official python docs, followed by the official docs for string functions. Bing does the reverse, pointing to string functions first, then the types page. All good.
• “java string” — Google’s top result is the official Java 1.5 Javadoc for String. This should probably be v1.6 (aka Java6 SE, aka whatever label the Sun marketing department was using that month), but v1.5 isn’t bad. Bing’s top result is the official String page… for Java v1.3. Oops!
• “c# string” — Bing and Google both point to the official MSDN string type documentation.
• “ruby string” — Bing and Google’s both point to the official Ruby doc for the String object.

And so on. Not a whole lot to complain about.

A Vast Wasteland of JavaScript Tutorials

But when it comes to JavaScript, Google and Bing both go braindead. The top result for “javascript string” is not something sensible, like MDC Strings. It’s a page owned by W3C Schools, a mediocre tutorial site. In fact, searching for “javascript anything” is very likely take you to W3C Schools. “javascript array“. “javascript split“. “javascript dom“. More on W3C Schools later.

Searching for “javascript tutorial” is even more depressing. One could imagine a really great JavaScript tutorial, a tutorial written from the ground up for the modern era. But we’re not looking for greatness; we’re just looking for “avoidance of really dumb stuff.” With that bar in mind, here’s what Google’s Top Ten gets you:

• Tutorials that feature document.write() front and center with no caveats: 8
• Tutorials with no syntax highlighting: 7
• Tutorials that waste time explaining how to write inaccurate browser detection scripts: 4
• Tutorials that include HTML comments in the script element, despite the fact that this is only necessary if you are designing for Netscape 1.0 and Mosaic: 9
• Tutorials that devote more than half their page real estate to ads: 4
• Tutorials with hilarious old skool background images and clip art: 1

Every single one of these tutorials is completely disconnected from modern frontend engineering practice. They were written in an era when the competition was Java applets. And yet over a decade later, Google and Bing still link to them.

HTML: Party like it’s 1999

The situation for HTML tutorials isn’t much better. From Google’s first page of results for “html tutorial“, you get:

• Tutorials that engage in unironic discussion of font, basefont, align=center, vlink, or other nonsense: 5
• Tutorials with no syntax highlighting: 7
• Tutorials that suffer from a fundamental confusion about tags vs. elements: 5
• Tutorials that contain detailed instructions on how to use the applet element: 3
• Tutorials that devote more than half their page real estate to ads: 3
• Tutorials with hilarious old skool background images and clip art: 3

There’s actually one tutorial on the first page that is kinda sorta okay. But you have to click through to Page 2 to get to a truly excellent, modern HTML tutorial. That means HTML is arguably ahead of JavaScript, if not by much.

A Great Vampire Squid Wrapped Around the Face of the Webdev Community

When I first started writing this piece, I thought there was no reason to pick on any of these sites by name. Most of these tutorials were written long ago by well-meaning people and then abandoned. If these obsolete tutorials still SEO well after all these years, that’s not their fault, that’s Google and Bing’s fault.

But it soon became clear there would have to be an exception.

Say what you will about W3C Schools — they are geniuses at SEO. They are the #1 HTML tutorial. The #1 JavaScript tutorial. The #1 CSS tutorial. The #1 PHP tutorial. The #1 SQL tutorial. The #1 ASP tutorial, the #1 SOAP tutorial, the #1 XML tutorial, the #1 Flash tutorial, and many many more. W3C Schools just dominates nearly every important technology for building web apps, at least as the world understood web apps in 2003. Unfortunately, some of those same technologies are still very important for building web applications today.

W3C Schools tutorials aren’t actually the worst out there — the field is pretty bad — but they’re awfully mediocre. Each tutorial is a flat list of concepts, all treated equally. A typical tutorial page consists of NAME OF CONCEPT, a couple of sentences about CONCEPT, and a short code snippet that includes CONCEPT. Then click NEXT. No meaningful discussion, advice on best practices, pitfalls, etc.

Now don’t get me wrong — you can’t fault someone for trying to make an honest buck by maximizing ad impressions while minimizing content production costs. Still, I would argue that this pedagogical approach is not necessarily optimal. To make matters worse, some of the material is actively harmful.

• The HTML tutorial is weak tea, but at least it doesn’t exactly do anything really atrocious. I would like it to have discussed CSS in a more integrated way. Or provide some real context or guidance. But whatever. It does omit a good deal of the bad stuff. There are far worse things out there.

• The JavaScript tutorial is more dangerous. Heavy usage of document.write(), silly browser detection scripts, and other things that would give poor Douglas Crockford a heart attack. The script element is shown going anywhere in the document you please without a word about performance considerations. Et cetera. Nor is there any larger discussion of how to actually use JavaScript, but of course there’s really no room for that kind of stuff given the format.

• The PHP tutorial isn’t as fundamentally important as HTML and JavaScript, but I thought it would be worth checking out. I was pleasantly surprised to discover that it actually has some meat on its bones — its pages have more substantial code examples, and there’s actual advice on what to do and what not to do. There’s even discussion on how to sanitize your inputs, imagine that! Sadly, the MySQL section is seriously broken. Nothing about PDO or even mysqli_connect() — it’s all about the old, dangerous mysql_connect() API. Yuck.

Anyway, this is what Google, and therefore newcomers to the subject, think is the best educational material to be found. Which means that thousands of people every day are learning all kinds of things that they will have to unlearn months or years later. Or worse, will never unlearn.

What to do?

In the beginning, there was a primeval explosion of HTML and JavaScript tutorials. Today, we are living with the decaying remnants of that explosion. Ordinarily these remnants would be invisible, but thanks to powerful, expensive instruments such as Google, we can detect them even today. Isn’t science awesome?

Well, we can’t exactly launch the Space Shuttle to install a corrective lens in Google’s optics.

Or… can we?

For starters, yes we can… whine to Google and Microsoft. A lot. And loudly! Shame them into fixing their algorithms. There are thousands of Google and Microsoft engineers using JavaScript too, and they must be embarrassed at how poorly they’re performing for these queries.

I also think the organic SEO approach is worth pursuing. The Promote JS! project is a an interesting start. More links pointing to the good stuff from more trusted sites — probably couldn’t hurt.

Finally, we need a new generation of modern HTML and JavaScript tutorials to flood out the crap that’s currently there. You only need one canonical version of the reference documentation, but when it comes to well-written, beautifully designed tutorials and guides, the more the merrier. Of course, propective tutorial writers should keep in mind that there’s no serious money to be made in this space, which is why we’re stuck with the fossils we have today. It’s going to have to be a labor of love — from today’s front end engineers to tomorrow’s. Awwww.