jQuery: writing plugin documentation

A jQuery plugin would be useless without a proper and detailed documentation. The key aspect to understand while writing your documentation is to address the most common questions that may come to a user's mind, for example those regarding installation and basic usages. Remember: your approach should always be as simple as you can. First, you should never take anything for granted when it comes to your audience. In fact, your readers may be skilled and advanced web developers who know exactly what they're doing as well as beginners who are simply trying to enhance their web sites some way. A first rule of thumb is: if you feel stupid by reading a plugin documentation, then the documentation itself is badly written. This happened to me when I first tried to use the SyntaxHighlighter library several months ago. I wasn't able to make it work because there was no clear example available in the documentation.

Here are some key aspects to keep in mind:

Include your documentation in the download file

Delivering your documentation online is fine, but from a usability perspective is more useful to include it in your download file. By doing so, a user can consult it and run his/her own tests even when he/she's offline.

Provide a browser support chart

You should test your plugin before delivering it. If you encounter some problems in one or more browsers, inform the user. There's nothing more frustrating than downloading and preparing your plugin only to find out that it doesn't work in the browser X, especially when such browser has to be supported on your site.

Combine code snippets with live examples

It's always useful for a developer to see the code first and then the live example, so he/she can copy and paste this code and see how it works. Never use live examples only, because a user is forced to view the source of your page to understand what's going on.

Include a copy of jQuery in the download file

I generally use the copy hosted by Google's CDN in all my examples, but sometimes I work on a PC that has no connection. So it's preferable to use a local copy of jQuery and include it in your download file.

Simple and advanced examples

You should always break down your examples into simple and advanced. By doing so, you can actually address the needs of those who have only recently downloaded your plugin as well as the needs of more advanced users.

Explain all plugin options carefully

"What happens if I use the option x instead of option y?" asks the user. You should always provide detailed examples for each option included in your plugin, starting from the default ones. Explain all combinations carefully, with full details, providing also live examples.

Provide a minified and normal version

Always minify, not obfuscate. Provide also the non-minified version of your plugin in the download file, so your users can study it and learn from it.

Provide minified and normal CSS files

If your plugin uses CSS and graphics, provide also a minified version of your style sheet, especially when it has reached a certain weight. A non-minified version is useful for changing styles more easily.

Provide graphic templates

Graphics include everything related to images. If you use graphics combined with CSS, it's useful to provide some kind of templates (such as Photoshop PSD files) in order to allow a user to modify the default design.