The following is a checklist of actions for you to go through to help ensure that your plugin's documentation is reasonably sound.
Include full examples. Short little code fragments are only relevant after you've demonstrated a full example. Zoom out a little bit and include a couple of lines of code before and after your example—they are invaluable in helping to put your examples into context. Take the time to demonstrate a few use-cases, and don't be cheap. If people repeatedly ask you how to do something related to your plugin, you should thank them for the interest and demonstrate a viable solution. Remember that they are asking you for a phrase, not a definition—an example demonstrates how to perform a specific task in its entirety. Assume that your audience is knowledgeable, but pretend they have had five or six beers, so you have to be extra clear in your explanations.
At the top of each file, include a brief description that identifies what it is and what...