YUI Raptors Will Eat Your Face

To my surprise, it turns out I have some influence over which animal will appear on the cover of the book. So I threw the question out on the internal YUI team IRC channel. As expected, the results were unsatisfactory.

To protect the guilty, all IRC nicks have been further anonymized.

  • [3:12pm] evangoer: Okay, important business.
  • [3:12pm] evangoer: My editor tells me that while I cannot choose the O’Reilly animal for the cover,
  • [3:12pm] evangoer: I can send her a list of suggestions.
  • [3:12pm] evangoer: So: floor is open
  • [3:12pm] MrPink: NARWHAL
  • [3:12pm] evangoer: ooh good start
  • [3:12pm] MrPink: Failing that, Moby Dick.
  • [3:12pm] MrPink: Or, really, any albino sperm whale.
  • [3:13pm] MrBrown: t. rex
  • [3:13pm] MrWhite: camel spider?
  • [3:13pm] evangoer: I was going to say velociraptor, but T Rex > Velociraptor
  • [3:13pm] evangoer: way too scary, Mr. White
  • [3:13pm] MrPink: If there’s a camel spider on the book, it will never enter my house.
  • [3:13pm] MrWhite: Has someone taken the angler fish?
  • [3:13pm] evangoer: yup bad marketing
  • [3:14pm] MrBrown: ditto
  • [3:14pm] evangoer: female or male angler fish?
  • [3:14pm] MrWhite: haha
  • [3:14pm] MrOrange: Velociraptors are scarier than T. Rex, IMHO.
  • [3:14pm] MrBlonde: Yeti Crab
  • [3:14pm] MrBrown: If they want a list, we should put both
  • [3:14pm] evangoer: yes but T. Rex kicked their butts in Jurassic park 1
  • [3:14pm] MrWhite: velociraptors are a fad (like the internet). T Rex has stood the test of time.
  • [3:15pm] MrOrange: True. But T. Rex couldn’t enter the computer room and kitchen.
  • [3:15pm] MrBrown: Mr. White: Good point.
  • [3:15pm] MrPink: YUI is clever. Like a raptor.
  • [3:15pm] MrPink: Also, learning YUI will help you open doors.
  • [3:15pm] MrOrange: Mr. Pink++
  • [3:15pm] evangoer: YUI will crunch through your problems like the jaws of a T. Rex.
  • [3:16pm] MrBlonde: Red Panda ‘(“shining cat,” from a Latinized form of the Greek, ailouros, “cat,” and the participial form of the Latin fulgere, “to shine”)’
  • [3:16pm] MrPink: Also, it’s modular. The modules work together to overcome problems, in much the same way that raptors work together to eat your face.
  • [3:16pm] MrWhite: Isn’t there a flying snake?
  • [3:16pm] MrPink: Mr. White: HOLY HELL WHERE KILL IT
  • [3:16pm] MrBrown: I think its a common misnomer that the T Rex is not as smart as the v-raptor. A consensus of paleontologists agree the T Rex is as smart as they come.
  • [3:16pm] MrPink: That said, as awesome as raptors are, narwhals are infinitely awesomer.
  • [3:17pm] MrWhite: 9 out of 10 paleontologists agree…
  • [3:17pm] MrBrown: Apparently, they are the most intelligent hunter evah
  • [3:17pm] evangoer: oooh the red panda is cute!
  • [3:17pm] MrPink: 1 out of 1 paleontologists I live with would agree with Mr. Brown’s stance on T-Rexes.
  • [3:17pm] evangoer: “its population is estimated at fewer than 10,000 mature individuals.” Well that’s YUI for sure.
  • [3:17pm] MrBlue: So, technically an animal: the YUI J-Pop star in illustration format on the cover?
  • [3:18pm] MrPink: 1 out of 1 paleontologists I live with would also like me to recommend the humble compsognathus, which she thinks is cute: http: //en.wikipedia.org/wiki/Compsognathus
  • [3:18pm] MrBrown: Mr. Blue: thread winner!!!
  • [3:18pm] MrPink: Mr. Blue: Ha.
  • [3:18pm] MrBlonde: We should get the “Distinct George” on the cover..
  • [3:21pm] evangoer: Alright, well fantastic work, gentlemen. Will send this out to O’Reilly post-haste.


When I started working on the YUI 3 Cookbook, I spent more time than I should have waffling on how to format the code examples. The most obvious way to go would be to show the entire page, like this:

<!DOCTYPE html>
        <title>Some Code Example</title>
        <div id="demo"></div>

        <script src="http://yui.yahooapis.com/3.4.0/build/yui/yui-min.js"></script>
        YUI().use("node", function (Y) {

That’s a lot of HTML line noise for three lines of JavaScript. Possibly okay for examples that are many dozens of lines long. But most recipes in the Cookbook just illustrate a single principle, and so are deliberately quite short.

A better approach, I thought, would be to strip away all the markup and keep the focus on the JavaScript:

YUI().use("node", function (Y) {

The JavaScript would be understood to be running in a boilerplate page with a handy demo <div>, a <script> element to load the YUI seed file, and maybe a yui3-skin-sam class on the body. I figured that designing the right boilerplate would cover over 90% of the examples — any example that needed slightly different markup could just show the full HTML.

But as I started working through the recipes, I discovered that no matter how I tweaked the boilerplate, I never got close to 90%. It was more like 60%. Some examples in the Loading chapter needed a different <script> URL. Other examples didn’t work very well with with a single demo <div> — they needed multiple <div>s, or a <ul>. Or they needed some unique CSS classes. I found myself distorting the JS examples to fit the HTML boilerplate. Not good.

So I dropped that plan and went back to showing the entire page, but with structural open and close tags stripped out.

<!DOCTYPE html>
<title>Some Code Example</title>

<div id="demo"></div>

<script src="http://yui.yahooapis.com/3.4.0/build/yui/yui-min.js"></script>
YUI().use("node", function (Y) {

Valid HTML, minimal line noise, consistently shows the reader the complete context that the JavaScript is running in. Success!

Of course, omitting optional tags from the markup isn’t anything new and exciting. This is how HTML has worked forever. It was a particularly useful feature to have in your pocket back in 2003-2004, the era when misinformed XHTML advocates were running around that XHTML was kewler and in particular, “more efficient!” than HTML. Thanks to some very aggressive marketing from various Industry Thought Leaders, the webdev community had managed to conflate “XHTML” with “clean markup” and also “CSS-based layouts.” So you had to gently point out to people that not only was it possible to write clean HTML 4.01 Strict, but an HTML 4 page would always be shorter than the equivalent XHTML. It took time to undo the damage, but these bad memes have long since been banished to low-information “webmaster” forums, setting up the larger community to receive and accept HTML5. You’re welcome, Thought Leaders!

Anyway, after working with a leaner style for a while, what surprises me is that it’s the exception, not the norm. Omitting <html><head>, and <body>means:

  • Fewer bytes. Actually, this is the weakest argument in favor, because we’re not talking about a large number of bytes. You could save even more bytes by dropping close tags (which in some cases I’m okay with) and by unquoting your attributes (which makes me queasy). Eventually you start crossing over into the world of HTML minification, which seems a tough nut to crack.
  • Less line noise. The difference is most obvious for short code examples. But even in a real world page, cruft is cruft.
  • Simpler indent style. This is something that’s bugged me for nearly fifteen years, and possibly the biggest win. Do I indent the <head> and <body>? Do I indent the direct children of the <head> and <body>? Using a lean style removes all of these annoying decisions. The elements you actually care about start flush left. End of story.

My guess is that the reason this style looks weird has to do with pedagogy. Since the early 90s, HTML books and tutorials have all shown these structural elements explicitly. This is a good idea because it helps new students understand the structure of the document. Or if you didn’t learn by reading a book or tutorial, you probably copied-and-pasted your code from someone who copied-and-pasted their code from someone who did.

However, professionals don’t need this crutch anymore. Better to just put the head stuff at the top, the body stuff below that, and separate the two with a newline. Boom, done. It will stop looking weird and start looking AWESOME in a day. Two days, tops.

One solid technical reason to have an explicit <body> is if you need that element stamped with an ID or class before JavaScript loads. Or you might be following an in-house coding convention or style guide, which of course trumps anything above.

The one thing I’m not concerned about is that people will read the code examples in the YUI 3 Cookbook and exclaim, “OMG that’s broken HTML!1!” The audience for the Cookbook is JavaScript developers, and in particular, JavaScript developers who are looking for a framework good for building large, sophisticated web apps. At that point, the reader really needs to know how HTML works. If they don’t, they probably bought the book too soon.

JSTutorial.net is Up (Sort Of)

Per Echo Nolan’s suggestion, I’ve put up jstutorial.net as a simple static page with links to modern JavaScript tutorials. This is just a temporary measure (although “temporary measures” have a funny way of becoming permanent).
The site lists only two resources right now: Ilya Kantor’s The JavaScript Tutorial and Marijn Haverbeke’s Eloquent JavaScript. This is a pretty tiny list, so any further suggestions are most welcome. The submission guidelines from the site are repeated below.

JSTutorial.net Submission Guidelines

If you have a tutorial to suggest, please contact me. Any suggestion must A) at least be on par with the resources listed above and B) at least make some attempt to target non-programmers in the introductory lessons. There are many sites that meet A) but not B), or vice versa.

Here’s what will instantly disqualify a site:

  • Showing how to use <!-- //--> comments to hide JavaScript within <script> elements.
  • Providing a first example that uses alert() or document.write().
  • Attaching events using the onclick or related HTML attributes.
  • Covering the page with ads, branding, and other extraneous crap to the point where it’s impossible to focus on the actual text.

In other words, a late 1990s tutorial that has been sitting around collecting ad revenue for the last fifteen years will not make the cut. Even if it ranks well on Google. Sorry.

Posted in Web

Search Engines and JS Tutorials: Still Appalling

About a year ago, I observed that ancient HTML and JS tutorials were choking the web like kudzu. Fast-forward to the present day, and… nothing has changed.

Focusing on Google results for JS tutorials (Bing is equally bad):

  1. On the first page of results for “javascript tutorial”, every single result ranges from bad to truly awful. My proxy for “bad” is, the first example A) uses fallback comments for Netscape Navigator 1.0 and B) uses alert() or document.write(). Most tutorials go rapidly downhill from there.

  2. The 1% of users who somehow manage to click through to the second page of results will finally stumble into the first good link in position #14 — Eloquent JavaScript by Marijn Haverbeke. This is an excellent JavaScript resource, well-written and modern. I own the dead-tree book and recommend it highly. Haverbeke bills Eloquent JavaScript as an “introduction to the JavaScript programming language and programming in general,” but I think that aside from the first chapter on variables and control flow, the book is too sophisticated to be an introductory tutorial.

  3. The third page of results includes the Mozilla Developer Network JavaScript docs, which are excellent but in no way a tutorial. It also includes a JS tutorial written by jQuery inventor John Resig, targeted at experienced programmers. Finally, in position #29, an actually useful JS tutorial site appears, javascript.info. javascript.info is well-organized and comprehensive. It’s not hideously ugly and slathered with ads. The early lessons ignore legacy nonsense from 1995. It’s pitched at the right audience. We have a winner!

This state of affairs has made me angry. So angry in fact, that in a fit of pique I ran out and registered jstutorial.net. That’s like making someone mad enough to take a $10 out of their wallet and tear it up right in front of you. That’s angry.

After the YUI 3 Cookbook draft is done, I’m going to check one last time to see if anything has changed. I’ve registered a domain name, people. Don’t make me use it.

The YUI 3 Cookbook is Underway

It’s already been announced on yuiblog, so it’s probably high time it got mentioned here. On March 1, I started writing the YUI 3 Cookbook, due from O’Reilly Press early next year.

This is all on top of my regular job, so taking on this project has unfortunately meant some… lifestyle cutbacks. For instance, there’s a guy at work who has decorated his cube and the adjacent hallway with posters and paraphernalia from every newly released computer game known to man. This means I have to steel my nerves and walk past a Dragon Age II poster every day. Every day, people!

Those sacrifices aside, I’m thrilled that YUI team asked me to work on this project, and my wife and young son have been enormously supportive about the whole thing. At least, I think my son is supportive. Whenever I ask him about it, he says “Hey!” and tries to chew on my finger, which I’m pretty sure means, “Go Dad!” Either that, or he’s saving up his grievances for later.

Some info about the YUI 3 Cookbook, in order of priority:

  • No, I do not know which animal is going to be on the cover.
  • The material will focus exclusively on YUI 3.
  • The cookbook will contain over 200 recipes. Each recipe has the form “Problem”, “Solution”, and “Discussion”, much like other cookbooks released by O’Reilly.
  • The total length will be on the order of 500 pages, including TOC and index.
  • In the YUI Library forums, I’ve created a thread with links to a strawman TOC and a sample PDF. The material is completely unedited, not technically reviewed, and riddled with red TODOs. But it should give you an idea of the scope and style.

Much more to come.

XML: Not Great for Documents, Actually

Norman Walsh, “Deprecating XML“:

“In short, if all you need are bundles of atomic values and especially if you expect to exchange data with JavaScript, JSON is the obvious choice. I don’t lose any sleep over that.

XML wasn’t designed to solve the problem of transmitting structured bundles of atomic values. XML was designed to solve the problem of unstructured data. In a word or two: mixed content.”

Daniel Lemire, “You probably misunderstand XML“:

“Thankfully, it appears that history is on my side. Developers got tired of getting these annoying XML payloads. In time, they started using JSON, a much more appropriate format for passing small loads of structured data between a server and an ECMAScript client…

Where does that leave XML at? Precisely where it started. XML is a great meta-example on how to deal with semi-structured data. And it is just as useful as ever. Want to deal with documents? DocBook and OpenDocument are great formats.”

Speaking as a technical writer who has spent the last several years authoring DocBook, customizing DocBook stylesheets, and writing build scripts around DocBook: no. No, DocBook is not a great document format. It is an acceptable document format.

First, I’ll grant that DocBook is vastly superior to the proprietary binary formats that came before it, for all the obvious reasons: you can diff it, you can check it into version control, you can edit it with just about any editor you like on any platform, the base toolset is free, et cetera. That’s kind of the minimum you want to see for any modern documentation format, and with that in mind, I am thrilled to use DocBook over, say, AuthorIT or Word. (I actually still miss FrameMaker, but DocBook wins there too, unless your only output format is a 7″x9″ perfect-bound book.)

Second, DocBook contains a number of critical design errors that, to be perfectly fair, have nothing to do with its XML nature. The fact that man pages require a completely different syntax from books and articles is not XML’s fault. The frightening size and complexity of DocBook’s vocabulary is (probably) not XML’s fault.

But even ignoring these flaws, DocBook is saddled with a number of XML-related problems:

  1. As an XML document format, DocBook has tied itself to the boat anchor of XSLT. The DocBook stylesheets expose a wide array of fiddly knobs to turn using parameters, and if you just stay in that space, you’re basically okay. But if you want to do a more aggressive customization — say, have a full TOC on the left hand side of every page — you are screwed. You either need to do radical field surgery on the stylesheets, with the patient screaming and fighting you all the way. Or you need to throw away the XSLT and transform DocBook some other way, starting over from scratch.

  2. As an XML document format, DocBook is an unproductive authoring environment. Even though I’ve been successfully hand authoring angle-brackety things for my entire professional career, and even though I’m aware of a vast array of tools to make hand authoring angle-brackety things easier, I am choosing to author this post in Markdown, not HTML or DocBook. Why? Because no tool is ever going to change the fact that creating a list by typing “n1. As an XML document format…” is easier than typing a slew of open and close tags.

    DocBook also penalizes you on reads as well as writes. DocBook is readable, in the sense that it can be read. Lightweight markup languages like Markdown and reStructuredText are readable, in the same way that a book is readable.

    And yes, there are a couple of decent semi-WYSIWYG DocBook editors out there. I even use one! It is so choice. If you have the means, I highly recommend picking one up. But that’s kind of the point — these tools are just an expensive patch to make up for the massive productivity loss of actually writing DocBook XML directly. (“But wait!” you cry. “I’ve set up all kinds of clever DocBook shortcuts and macros in my editor!” That’s swell. You are still wasting huge amounts of time. Stay the hell off my doc team.)

  3. As an XML document format, DocBook is forced to use draconian error handling. One mistake and parsing must stop, you’re done. The thinking behind this feature was that if you’re sending a transaction to your bank, and the payload is malformed, you don’t want the bank’s server “guessing” what you might have wanted.

    But novels and articles and technical manuals are not bank transactions. If I forget to close an inline tag, or I screw up a cross-reference, that’s not a good thing. But should a minor mistake break my doc build? For my team, I lean towards an answer of “yes.” You, however, write in a different environment, for a different audience, and perhaps have a different answer for how you would prefer to run your workflow. But screw what you and I think. The XML specification has made that decision for us.

    Oddly enough, draconian error handling was built for the very use case that XML evangelists now seem to be backing away from. Okay, JSON has superceded XML for data interchange on the web — but that’s just fine! XML was always for document formats, really.

    If XML is more or less popular than JSON among front end engineers, it’s really not a big deal to me. I don’t write web APIs for a living, I just write about them.

    But if people are arguing that XML’s core strength is in documentation, then as someone who writes documentation full time, let me say that this is just bunk. That might have been true in 1998, but today there are better choices out there. Markdown is simple and has multiple implementations. If you need something more powerful, reStructuredText + Sphinx has a rich feature set that in many places matches DocBook, but with far less complexity.

Not that DocBook is terrible. However, its XML lineage is not an asset. XML is not the best way to say, “Here is a paragraph. Here is a list item. Here is an index entry. Here is a cross-reference.” Don’t let anyone kid you into thinking it is.

YUI 3 Grids are Dead Simple

If we were summarizing the history of webpage layout technologies, it would look something like the following.

  • 1990 — 1993: Before the Dawn of Civilization. Wandering hunter-gatherer tribes use only the primitive tools available to them: headings, lists, paragraphs.
  • 1994 — 1997: The Tabular Empire. The invention of the “sidebar”. Enterprising tribes settle down and begin building magnificently complex structures.
  • 1998 — 1999: The Baroque Period. Monuments constructed by the Tabular Empire grow increasingly ornate and unstable. The Browser Wars threaten all civilization. Meanwhile, barbarians lurk out in the steppes, armed with increasingly sophisticated div weaponry.
  • 2000 — 2002: The Dark Ages. The economy collapses. Citizens flee into the unprotected wilderness, and many are absorbed into the barbarian tribes and learn their ways. It takes secret black magic to get anything to work at all. Only the greatest shamans are able to build anything in this cold, hostile environment.
  • 2003 — 2005: The Renaissance. People begin sharing knowledge. Great new schools of thought begin to arise on how to work around browser quirks.
  • 2006 — 2010: The Age of Enlightenment. Systematic investigation of the browser universe. Knowledge is codified. The rise of CSS frameworks.

My CSS framework of choice has long been my own employer’s YUI. YUI Fonts and YUI Reset (or their moral equivalents from other frameworks) have always been no-brainers. But YUI 2 Grids has always been more optional.

As an example, take this site’s layout. It’s currently a single column, so no need for a grid there. However, it does actually put two columns next to each other in a couple places — in the Comments form and in the footer. So I could have used Grids… but chose not to. First, YUI 2 Grids is several KB, which is large enough that I didn’t want to just throw it in there if I wasn’t sure I was going to use it. Second, it’s complicated enough (with its nested doc3s and yui-t6s and yui-u firsts and whatnot) that for simple things it’s easier to just do a homebrew solution. Float a div over, style it, peek at it in a couple browsers, and hope for the best.

That’s all changed with the recent release of YUI 3 Grids, new in YUI 3.2.0. Not only is this version tiny (1.5 KB), but it’s the first layout system I’ve ever used where I can just write out whatever grid I want from memory, without ever needing to look at the docs. Observe:

<div class="yui3-g">
  <div class="yui3-u-1-3">
  <div class="yui3-u-2-3">

View results here.

You can slice and dice up the parent yui3-g div into as many units as you like using yui3-u-numerator-denominator, going all the way down to 1/24ths. Or you can use generic yui-us and fix the widths of each unit to a particular pixel.

Nesting is straightforward as well. Just spawn a new yui3-g, and everything works as expected.

<div class="yui3-g">
  <div class="yui3-u-1-3">
  <div class="yui3-u-2-3">
    <div class="yui3-g">
      <div class="yui3-u-1-2">
        <p>2/3 * 1/2</p>
      <div class="yui3-u-1-2">
        <p>2/3 * 1/2</p>

View results here.

I’ve also been playing around with weird edge cases. At work, I have a project that generates 1-4 widgets in rows. I was curious to see what would happen with Grids if you leave a column out:

<div class="yui3-g">
  <div class="yui3-u-1-4">
  <div class="yui3-u-1-4">
  <div class="yui3-u-1-4">
  <-- Ruh-oh, missing div! -->

View results here.

Grids does the right thing again: it fills up the space with three columns, and leaves the fourth slot empty. This meant that I wasn’t forced to create a dummy div to fill up the space, which slightly simplified my backend code. Not that this was a huge win or anything, but still, a happy moment.

So I think at this point, there’s not a single site where I wouldn’t just go ahead and use all three of Reset, Fonts, and Grids. Huge thanks to Matt Sweeney for architecting the new Grids. It was worth the wait.

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

The Greatest Generation Really Was Pretty Great!

I’ve been reading Steve Blank’s outstanding series, The Secret History of Silicon Valley. Blank makes the case that much of the valley’s history has been simply forgotten, and the true starting point is at least 100 years ago:

I read all the popular books about the valley and they all told a variant of the same story; entrepreneurs as heroes building the Semiconductor and Personal Computer companies: Bill Hewlett and David Packard at HP, Bob Taylor and the team at Xerox PARC, Steve Jobs and Wozniak at Apple, Gordon Moore and Bob Noyce at Intel, etc. These were inspiring stories, but I realized that, no surprise, the popular press were writing books that had mass appeal. They were all fun reads about plucky entrepreneurs who start from nothing and against all odds, build a successful company.

To my surprise, I discovered that yes, Silicon Valley did start in a garage in Palo Alto, but it didn’t start in the Hewlett Packard garage. The first electronics company in Silicon Valley was Federal Telegraph, a tube company started in 1909 in Palo Alto as Poulsen Wireless. (This October is the 100th anniversary of Silicon Valley, unnoticed and unmentioned by anyone.) By 1912, Lee Deforest working at Federal Telegraph would invent the Triode, (a tube amplifier) and would go on to become the Steve Jobs of his day — visionary, charismatic and controversial… By 1937, when Bill Hewlett and David Packard left Stanford to start HP, the agricultural fields outside of Stanford had already become “Vacuum Tube Valley.”

The part that really struck me was the section about World War II, where Fred Terman and his colleagues were tasked with defeating Germany’s very sophisticated and secret electronic air defense system, which was responsible for inflicting unsustainable losses on Allied bomber crews. In an incredibly short period of time, these engineers completely transformed the nature of electronic warfare. Or as Blank puts it,

Just to give you a sense of scale of how big this electronic warfare effort was, we built over 30,000 jammers, with entire factories running 24/7 in the U.S. making nothing but jammers to put on our bombers.

By the end of World War II, over Europe, a bomber stream no longer consisted of just planes with bombs. Now the bombers were accompanied by electronics intelligence planes looking for new radar signals, escort bombers just full of jammers and others full of chaff, as well as P-51 fighter planes patrolling alongside our bomber stream.

Unbelievably, in less than two years, Terman’s Radio Research lab invented an industry and had turned out a flurry of new electronic devices the likes of which had never been seen.

Aside from catching up on my history, the other thing I’ve been doing is moving the HTML tutorial out of WordPress completely and into the new template. This also gave me the opportunity to do some cleanup — fixing typos, outdated sections, broken links, and so on.

One section of the tutorial discusses abusing HTML borders to do dotted underlines and other fancy decorations. Originally, I had a link to a 2003 version of the CSS 3 spec, which included the possibility of doing dotted underlines natively, using CSS text-decoration As I was editing, I thought it would be good to update the link to the latest version of the draft. To my surprise, the 2007 version of the section now says in red,

Paul and I have agreed that we want to simplify the set of properties introduced in the previous CSS3 Text Candidate Recommendation. We’re not sure how yet, though, and would like to solicit input from the www-style community.
So far, we think that the following capabilities should be sufficient…

Hmmm. Okay, so to recap:

  • In the early 1940s, Fred Terman’s Radio Research Lab spawned an entire new industry in a couple of years, based on far-out science-fictional technology, shipped product, and helped win the war against fascism.

  • Meanwhile in the 2000s, after nearly a decade, we still can’t figure out how to do fancy underlines.