One of the most frequent reasons of failure for a jQuery plugin (and also one of the most frequent causes of frustration for users) is when a plugin is poorly documented. It doesn't matter if the plugin in question is stunning and a real masterpiece of the finest jQuery coding ever seen because what users need is to understand how a given plugin works and how they can configure it to make it suit their needs. The first thing to bear in mind while writing your plugin documentation is to provide all the information that a user may need. Explaining the basic configuration options of your plugin is not writing a documentation, but simply provide the minimum information required. Of course this is not enough, because users usually need more. I know that because I made this mistake myself.
Instead, you should also provide a detailed description of each option and how this option work to get a given effect. You should devote more than a single page to your plugin documentation and more than a single example. For each option, you should create a page containing:
- syntax
- description
- live example
Finally, you should provide a complete, final example with all the options working together, or more concrete examples showing all the possible combinations.
If your plugin works with a predefined set of HTML elements or custom CSS selectors, you should always devote a detailed explanation to the default HTML and CSS structure of your plugin by clearly specifying that your plugin works with a given set of HTML elements and with some predefined CSS selectors.
For example, if you've created a content slider plugin that automatically wraps a series of slides with the following HTML structure:
<div class="slider"> <div class="slider-wrapper"> <!--slides here--> </div> </div>
you should describe this structure so that a user can use its own CSS styles on it, for example to change the default position of the slider on the page. Further, if your plugin requires that every slide must have a CSS class named slide to be used within your content slider, you should also describe the way by which a user can change this default class with a custom class.
If your plugin has dependencies (e.g. another jQuery plugin or framework such as Easing or jQuery UI), you should also specify that your plugin requires them to work, because users tend to be easily distracted and often forget some important details. In that vein, you should never provide your documentation as JavaScript comments because the source code of a jQuery plugin is rarely studied by normal users (only by developers).
When you package your plugin, you should create a directory for your documentation and examples. The best thing you can do is to link your documentation page with its corresponding example. If so, you can create the following directory structure:
/documentation /examples
Alternatively, you can include the live example within the documentation page. It's vital to create a file hierarchy that can be consulted with a web browser by jumping from a page to another. You can create a default index.html file for that purpose:
/documentation index.html page1.html page2.html pagen.html
This is the same approach followed by jQuery UI. I recommend this approach because it's really helpful for users.