Ancient HTML and JS Tutorials are Choking the Web Like Kudzu

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 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.


I’m trying out a new feed reader called Fever. So far, I like it. Even if I didn’t like it, at the very least Fever’s creator Shaun Inman deserves major credit for diving into a moribund marketplace and trying to create something new and interesting.

Fever is a collection of PHP files that you install on your own server, sold for $30/pop. There is no central hosting, so if you don’t have access to a server, you’re out of luck. At first glance this seems like a crazy business decision. On the other hand:

  • running a hosted service is a PITA
  • in 2010, anyone who is actively looking for a new feed reader is almost guaranteed to be a nerd who has their own server

More interesting than Fever’s basic architecture or business model is how Fever treats feeds and entries. There are three basic categories:

  • Kindling — feeds that you want to read on a regular basis. Family, friends, important stuff.
  • Sparks — feeds that you don’t really care about reading regularly. These feeds only really exist as fodder for the Hot list.
  • The Hot list — a list of links that Fever has determined to be relevant based on the contents of your Kindling and Sparks.

For example, one of the top entries in my Hot list right now is “Do you skim?” In NetNewsWire, I would have seen this post anyway, since is one of my daily reads. However, Fever boosts this post to the top because the link is also referenced by SFSignal (a Spark) and a couple of science fiction author blogs (also Sparks). Another link in the Hot list is a PDF article in National Affairs by Robert Solow, “Science and Ideology in Economics.” I don’t subscribe to National Affairs at all, but that link appeared in a couple of my Sparks, so poof! there it is.

What I love about this design is that it mirrors how I actually want to think about feeds. There are my actual friends and colleagues who I want to pay attention to, plus a small number of pro blogs that are consistently interesting. And then there are feeds that are sort of interesting, but just not worth the cost of adding to the feed reader. But in Fever, you can just throw lower-priority feeds into Sparks and never have to think about them again. If anything interesting happens, Fever will bubble it up. In traditional feed readers, this kind of thing is a chore — I know I can only keep up with so many feeds, so every new feed is a costly decision. Fever solves this problem elegantly. It’s actually kind of liberating to race around the web, adding feeds again.

The other brilliant thing about Fever is that unread counts are not shown by default.

What are my issues with Fever?

  • The only big one is, reading authenticated feeds does not seem to work, at least not with protected LiveJournals. This only affects a couple of my feeds, but it’s something I really need to figure out before I’ll be able to wean myself from NetNewsWire entirely.
  • This might be pilot error, but as far as I can tell, links in the Hot list don’t seem to have the concept of “Read / Unread”. Instead, they have a “Blacklist” button that nukes the link from view. There’s something a little off about having only this metaphor for clearing up the Hot list.
  • Building up Sparks is pretty fun, but you have to be careful to keep things balanced: if you add a bunch of SF writer blogs, you need to add a roughly equal number of econ blogs, and so on. Otherwise one group will start to dominate. (SF nerds vs. econ nerds: FIGHT!)
  • So far, Twitter appears to be useless. I’ve added a few of the people I follow on Twitter to Sparks, and either these test feeds don’t include enough overlapping links to make a difference, or Fever is getting confused by Twitter’s link shorteners. Screw link shorteners and screw Twitter.

So next up, figuring out the auth problem. After that, pulling in my Facebook activity and turning it into a dedicated private feed for Fever to consume. Thanks to Facebook’s EVIL PRIVACY-DESTROYING BABY-KILLING Graph API, I think that project might be easy enough even for me.