13 September 06

Please get your documentation sorted

I’ve been trying to write this post in various different ways now. Trying to be polite but get the message across. Being jokey so they won’t think I’m a knob. But seriously, anyone who’s involved with a Javascript library, be it Prototype, jQuery, dojo, or any similar project: Please, please, please get your documentation sorted. Seriously. You’re putting people off your library by being so difficult to comprehend.

Here is a list of my opinions on Javascript library documentation. The ratings have nothing to do with the particular library, just solely on the quality of documentation.

Prototype: No links, or any sign of help at all, on the home page, nothing at all in the download zip too. Maybe Sam, the lead developer, should talk to Sergio Pereira, who has done an unofficial guide, which is great (although could do with a few more examples).
Rating: D

script.aculo.us: Wiki-based, with no decent structure to it (like most wikis then…). Some of the source is entirely Rails based – i.e. not very helpful. Messy and could do with some work.
Rating: C+

dojo: The standardista’s nightmare library has its ‘obsolete’ half-documented reference manual still linking from it’s front page. Hardly any simple examples with API reference. The dojo book is good for an introduction but a bit of a slog. Definite signs of promise but needs severly tightening up.
Rating: B-

jQuery: My personal favourite JS library, but the documentation is all over the place. If I was a new user, I wouldn’t have a clue where to start. Seriously needs someone to organise the docs into a logical order, with strong examples and API methods. Visual jQuery is organised well, but lacks any proper detail.
Rating: C+

YUI: More like it – good examples, great tutorials, nicely set out code. Has a tendency to go off into tech-geek mode though, however, this can be easily changed.
Rating: A

Mochikit: Well set out, could do with a couple more examples online (there are some in the download zip file). Nicely written – not too heavy, but with enough detail.
Rating: A-

There we have it. Yahoo UI wins. This has nothing to do with the code remember – personally I wouldn’t like have ‘YAHOO’ everywhere – but their documentation makes it easy for new users to understand, and also current developers lives easy by providing high quality information about its code.

Enjoy this? Subscribe to the feed for the very latest updates.