If It Isn't Documented, It Doesn't Exist

Nicholas Zakas enumerates the number one reason why good JavaScript libraries fail:

Lack of documentation. No matter how wonderful your library is and how intelligent its design, if you're the only one who understands it, it doesn't do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.

James Bennett expresses a similar sentiment in choosing a JavaScript library:

There's one other thing which can really make or break a JavaScript library, and it's surprising how often it's overlooked, because the same thing makes or breaks an awful lot of software in other fields: documentation. The greatest library in the world would fail if the only way to learn it was reading the code (and, in fact, it already has to a large extent). Some packages have managed to overcome this by way of lots of unofficial documentation -- blog entries and the like -- but there is absolutely no substitute for full, well-written documentation. The ideal, for me, consists of:

1. High-level overviews of each part of the library, touching on key objects and methods.
2. Practical examples showing how to handle common use cases.
3. Full API documentation for everything in the library. JSDoc is both good and bad for this: good because it makes API docs stupidly easy to generate, and bad because people assume that API docs are all you need. Javadoc, which inspired JSDoc, has wrought much ill on the Java world for largely the same reasons.
4. Comments throughout the code itself.

Pretty much everybody who's developing a JavaScript library has dropped the ball on this; very few libraries manage even one or two of those points, and out of the teeming multitude of JavaScript libraries floating around today I've seen exactly one which manages to hit all four points with any kind of success. Maybe there are other splendidly-documented libraries out there, but I've yet to see them; most treat documentation like an afterthought.

Mike Pope, who writes documentation for a living, neatly summarizes both opinions with this zinger:

We've been known to tell a developer "If it isn't documented, it doesn't exist." Not only does it have to be doc'd, but it was to be explained and taught and demonstrated. Do that, and people will be excited -- not about your documentation, but about your product.

Good documentation is hard to find. Particularly on open source projects. That's why I was so pleasantly surprised to see such excellent documentation for the open-source UrlRewriting.net project, along with a support forum.

The UrlRewriting documentation (pdf) is a pleasure to read. Far from being an afterthought, documentation was a first-class citizen on this project, and it shows. The presence of good documentation makes the code a pleasure to use, too.

So how do you keep your documentation up to snuff on a rapidly moving project? Maybe it's possible to use agile documentation methods alongside agile coding practices. Mike Pope's recent post on the "agile little" ASP.NET AJAX documentation set is a hopeful sign that we, too, can generate better documentation, faster.