Yesterday, a Hacker News thread started about the recent yuilibrary.com site re-launch. The new template had drawn a good deal of praise from various Friends of YUI on the Internets over the previous few days, which made everyone feel pretty good.

But Hacker News lives very much outside the YUI community bubble, and feedback there was more mixed. One of the earliest comments set the tone:

While YUI is probably one of the best JS frameworks around the sloppy design of their webpage beats me. the yuilibrary.com looks so 90ish in its design.

Instead of letting the thread sit out there and rot, YUI engineer Ryan Grove quickly responded with:

What parts of it strike you as sloppy? How would you improve the design? We’d love to hear specific feedback.

And got comments like:

* Use a fixed-width site. Most people go for something like 960px. * Establish horizontal and vertical eyelines or columns. * If you're on Github, might as well use gists. Offer example projects as open projects on Github

+1 on the fixed width. I'm a developer, so I have a big monitor -- it's hard for my eye to follow sections of the document without lined up elements.

Trebuchet feels dated, especially when bolded and part of blue + orange scheme. That look was very trendy a few years ago. Also, too many faces. Two faces usually work fine...

... I know you have your own CDN but can we have back a "Download" button? I hate it when I have to search for 5 minutes to find out how to download something. It really makes me feel like the whole project is going to be a pain in the ass when even downloading it is hard.

About two hours later, Ryan responded again with:

Great feedback, everyone. I've pushed a few quick changes to address the low-hanging fruit:

- We're now using Maven Pro for headings (no more Trebuchet).

- Replaced Lucida Grande with Helvetica in the nav bar (sorry Windows users, you get Arial).

- The site now has a max width of 1200px instead of expanding infinitely. This seems like a reasonable compromise, since any purely fixed-width design draws the ire of people who hate fixed-width designs.

Keep the feedback coming!

We wanted to emphasize the CDN over downloads, but we clearly hid the download links too well.

I've added a "Downloads" link to the "Quick Start" dropdown menu in the top nav bar, and we'll give some thought to adding a more prominent link somewhere on the front page. Thanks for the feedback!

Not everything got fixed immediately, but some easy changes got pushed right away. And just like that, comments like this started appearing:

Thanks! That's a pretty amazingly quick response and makes it way easier to find.

Wow, that was fast.

All of a sudden with all of rgrove's (YUI's) interaction, it makes me feel all warm and fuzzy about using YUI again. Great customer service does make a difference.

No doubt not everyone was 100% satisfied, but the thread stayed popular for a good part of the day, and I think most folks came away with the feeling that the YUI team was responsive and effective. After all, they were in fact being responsive and effective. All in all, a good result.

However, the lesson here for the field of community management (at least when it comes to software products) is actually pretty grim.

The idea behind community management is that rather than letting feedback sit out there and decay, you have a professional someone whose job it is to come in and keep things from spiraling out of control. Talk to the people. Gather up the features and bugs. Communicate changes. Let people know that you’re listening.

But “listening” and “participating in the conversation” are weak sauce, and everyone knows it. It’s action that matters.

Having a community manager who is also a working engineer or a product manager makes sense to me. Those are people who can push changes. The icing on the cake is if your product allows for pushing simple changes very quickly. But even without that, just having real authority and knowledge over the timeline makes a world of difference.

By contrast, the classic dedicated community manager is someone who is bright and socially adept, someone who can funnel information back and forth, but who lacks real product authority. After all, you don’t want to waste a product person’s time doing that stuff, do you? Way too expensive. And they would suck at it. No, you need someone specialized.

More and more, that whole line of thinking seems like a huge trap.

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>
<html>
    <head>
        <title>Some Code Example</title>
    </head>
    <body>
        <div id="demo"></div>

        <script src="http://yui.yahooapis.com/3.4.0/build/yui/yui-min.js"></script>
        <script>
        YUI().use("node", function (Y) {
            Y.one("#demo").setContent("HELLOSKI");
        });
        </script>
    </body>
</html>

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) {
    Y.one("#demo").setContent("HELLOSKI");
});

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>
<script>
YUI().use("node", function (Y) {
    Y.one("#demo").setContent("HELLOSKI");
});
</script>

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.

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.

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.