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.