If It Isn't Documented, It Doesn't Exist
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.
- High-level overviews of each part of the library, touching on key objects and methods.
- Practical examples showing how to handle common use cases.
- 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.
- Comments throughout the code itself.
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.