User documentation is all too often written by programmers for programmers. It tends to focus on the products features, rather than the users tasks. Generally, programmers arent in the ideal position to be writing user documentation. Theyre too close to the bits and bytes, and theyre too far from the user. To them, what the product can do tends to be far more important than what the user can do with the product.
Its a subtle but vital distinction. Research shows that the key to effective user documentation is writing task oriented help. Even better, write your help according to the minimalist theory. In the documentation world, minimalism is a fancy word for a commonsense practice. In basic terms, it means write to your reader and keep it simple.
The theory itself has a lot of twists and turns. If you want to read a great but slightly wordy book on the subject, check out the book Minimalism Beyond the Nurnberg Funnel, 1998, edited by John Carroll.
In the meantime, if you can tick every item in the following checklist, youll be well on your way to usable online help that both your readers and your managers will thank you for.