jacobian.org

The good

Dojo is extremely powerful. With very little code I was able to make a really nice drag-and-drop reorderable table, complete with nice zebra striping and add/remove row buttons. (Wilson and I are working on a new kick-ass interface for Django’s “edit_inline” admin views, if anyone cares.)

I find the event system particularly awesome; the fact that the drag-and-drop code generates dragStart and dragEnd events (and friends) lets you do some really powerful stuff. In particular, you can copy (instead of move) the node on an option-drag and with that get yet another step closer to desktop-app usability.

I also like the dojo.require system of loading in bits that you need. All told Dojo is really large — over two megs of code — so some system like this is obviously needed. Props to the team for choosing a nice simple way of doing it.

Dojo’s code itself is quite well written, and most of the time well-commented. There’s some weird idioms in the code — I find the whole extension mechanism a little hard to follow — but they’re easy to get over.

I’m also a big fan of the convenience functions in dojo.dom. They’re the type of functions any Javascripter writes over and over again, so it’s nice to just have them there for you.

The bad

Dojo is really big, both in terms of download size and API size. The second isn’t much of a problem (more on that later, though), but the download size is a sticking point.

The require mechanism and the different downloadable versions are a good way of trying to keep page weight down, but there’s still a noticeable delay the first time I hit a Dojo page without any caching. I’m not sure there’s a way around this, and for a big app like Django’s admin I don’t think it’s an issue. Still, there’s probably more work that could be done here.

As I said, the API size isn’t too much of a problem — or rather, it wouldn’t be, if the documentation was any good. Which brings me to:

The ugly

I would say that Dojo’s documentation sucks, except that there’s no “it” to be sucky. I was eventually able to figure out what I wanted to do be reading through the code, but the fact is that it took me over an hour to write what amounted to 30 lines of code.

This leaves me in a pretty annoying situation: I’m very excited about the cool shit we could do with Django and Dojo, but I fear that without better documentation I’ll probably spend most of my time just reading through Dojo’s code. Yes, it’s well-written, but that’s no excuse for the sorry state of end-user documentation.

Now, I know first-hand how much effort writing good documentation can be — scratch that; writing any documentation is extremely hard — and I’m sure the Dojo folks don’t need me to tell them that they need to get their shit together. All I’m trying to say is that I really hope Dojo’s documentation gets a lot better so I can spend more time using it, and less time scratching my head.