I've been looking at
YUI 3, because I ought to know about it and I currently don't. I used YUI 2 for a few things and found myself perpetually frustrated with the documentation and the general feel of it, but I figured that maybe that was just me. (Disclosure: I'm a jQuery guy. Use it for everything. So I'm biased, right out of the gate.) Anyway, my frustration with the YUI documentation doesn't seem to have been alleviated in version 3. This is a case study in how someone new to the YUI 3 library sees the documentation. (Well, it's really a set of stream-of-consciousness rants, because that's the best way I can think of getting my sense of confusion and discombobulation across.)
The underlying problem I always had with the YUI 2 documentation was that the examples show how to do one specific thing but don't explain
why to do it that specific way, and don't seem very generalisable to do other similar things. So they're hard to learn from. The reference manual, on the other hand, is useless. It gives you a textbox and says "Start typing to find a property/method/event/config". If you already know what you're looking for, if you know which function you want to use but can't remember the order of the parameters that you need to pass to it, then that's fine. It's a dictionary. But you can't learn a language from a dictionary, and you can't learn the YUI from the reference manual. I hardly ever find myself thinking "I need to use the YUI.Get.script function but I can't remember the name of the parameters". Instead, I find myself thinking "I want to execute a JSON-P script; how do I do it?" Now, the jQuery documentation has a similar problem, to some extent, but critically it shows you all the functions in a list, so I can look through them and work out which is likely to be the one I want. The YUI does not. The jQuery docs also have inline executable examples with each function, so I can see working code and test it. The YUI reference manual does not.
But I shouldn't start with the reference manual. The YUI docs specifically say to
, so I did so.
The very first example is showing how to attach an event handler to a node. Fine as far as it goes (and I like the idea that you get passed a full-on event object to your function whether you're in a browser that supports that or not), but...the code in the example just drifts in space. It's not wrapped in an onDOMContentLoaded or anything. (I admit it's the first example, which means you don't want to load people down with infrastructure just so they can write a click function.) So, since there's a working example in the page, I looked in the source myself, and we get
YUI({combine: true, timeout: 10000}).use("node",
function(Y) {
... code from the example...
});
Ah, OK, so that's onDOMContentLoaded, is it? a new YUI function. I'm sure it'll be explained later.
Moving on, the next example explains onAvailable, onContentReady, and event:ready -- three different "is the thing ready for me to use" load events. (All of which make sense at different times, and are potentially useful.) That's all good, but...the previous example, even after I'd looked in the code, didn't use any of them! How did that work?
Ah, a feeling of doom creeps over me. More disclosure: I really, really don't like the Yahoo practice of putting your JS inline at the bottom of the page. I think it means that my JS isn't separated out into different files where it's easy to edit, it makes refactoring the page hard because you have to care exactly where your script elements are and be careful if you move HTML elements around, and it's a lot easier to teach people to make their JS unobtrusive if you can offer the rule "Put all your JavaScript in separate files and don't have any anywhere in your HTML". I know there are good reasons why Yahoo do it, and I accept those reasons. If I build a site which gets as many hits as they do then I'll test both ways and the extra three milliseconds you get from having the JS in-page without DOMContentLoaded may make a big difference. For most of the stuff I write, though, I don't like it and try to not use it. So, the first example was obviously reliant on that (because it's not hooking any load event at all), but didn't say so. Moving on, the
next example I read, about nodes, does the same thing. As far as I can tell, nothing anywhere in these examples has said "make sure you put this example code after the things it's referring to". If you don't do that (say, if you put it in the head because that's where you've been taught that JavaScript should go) then it plain won't work, and you won't know why. (Maybe I missed the 72-point red writing which says this? I hope I did.)
Next example I read (
event delegation, a thing I like very much): doesn't show why the clicked items turn green (obviously CSS, and indeed it doesn't take long to find the link in the source), but also...when I click on one of the items and it turns green, there's a subtle animation effect to it, as if the green colour expands out from the centre of the item. It's quite a nice effect. I can't for the life of me find what's doing it, though. (Doesn't do it in Midori, a webkit browser, so maybe it's Firefox?)
I spent ten minutes trying to work out why clicking on an item sets a class ("yui-pass") on that item and then alters text in all non-yui-pass items, rather than just using e.target. Of course, the reason is that a
second click on a different item should set that second item to green and not unset the first green item. Fine and dandy: a note about that in the example would have helped, though. Yes, the examples are there to demonstrate YUI, not to explain how to produce a specific effect, but...what people
want is a specific effect. Explaining how it works would help with that. Explaining the YUI parts of an example but not putting them in the context of the rest of the code is like explaining how to build a house with a two-hour lecture on bricks without ever mentioning that you need mortar to stick them together. "The rest of the code" here is a couple of lines, but the example would make much more sense if it was all explained.
Once I'd got this far, I started thinking, hm, hasn't changed, still the docs are written for someone who isn't me and I don't get them. So I started dotting around picking and choosing bits to look at rather than going through step-by-step. One of the features I like most about jQuery is that I can call a JSON-P script and still specify my callback function inline, rather than having to separate it out and give it a name and pass that name as callback=myCallback to the JSON-P script. (It gets given a name under-the-covers by jQuery, of course, so that the callback does have something to call, but I don't have to think about it. I like inline functions.) It's be useful to me if YUI 3 could do that, so I thought I'd have a look to see if it's possible. I don't
think it is, but...I can't tell. The docs don't seem to mention the idea of loading scripts that call a callback function at all. Instead, I think you're supposed to use
YUI.Get.script and read the JSON out of the nodes array that you get passed. Perhaps. Here we come back to my problem with the YUI docs: I know what I want to do, but not how to do it, and there's no way to answer my question. If there isn't an example dealing with it, I am out of luck.
Someone tell me how I ought to be reading the documentation. Maybe I'm missing something. But it does rather feel to me like the docs are reference material: they're there for people who already understand YUI. The examples are incomplete -- focusing on just the part you're trying to show is understandable, but if the example won't work without the other parts then you have to show the other parts too! If your example only works if it's wrapped with
YUI().use("node"), function(Y) { ... }) then you have to show that. If it only works if it's wrapped in DOMContentLoaded, or if it's placed at the bottom of the page in a script element, then you have to say that. Yes, it's a ballache to have to explain how events work and how loading works and not get to any real concrete examples until chapter 3 or 4 of your documentation. But
people need to know that stuff or your examples will not work when someone uses them without knowing the context.
