When writing documentation, you can write it in one of two languages: Designese or Engineerean.
The perfect example of Engineerean is your typical O’Reilly book. These usually begin with a panoramic view of the topic as a whole, and then outline the specifics of every tool available. Engineereans go from the inside out, taking in the building blocks of the language and then using those to move towards a finished product. While a native Designese speaker such as myself may not learn a whole lot from Engineerean language books initially, they’re still invaluable desk-side references, as their structure makes it very easy to look up a specific property or method.
However, when you write documentation in Designese, then you’re speaking my language. The Designese approach is a very practical one: we as a people are visual learners, and we crave lots of examples. The Designese work from the outside in, seeing the finished product first and then analyzing how it works and going inwards from there. Dan Cederholm’s books are a great example: he begins with a functioning demonstration site and then dives in and explains the various parts that make it work.
So how can we bridge the culture gap and appease the citizens of both nations? The obvious answer is to start with a bunch of visual examples, and then have a full alphabetical glossary. But there are more subtle touches, for example, the excellent Visual jQuery, which is ostensibly Engineerean but is full of useful before-and-after code examples.
If you want people to use your library/framework/whatever, spend as much time as possible to write good documentation, and try to make it as accessible as possible. I see documentation as being much like product marketing, and arguably as important as the product itself.