1) Evaluation stage: Developer arrives at API docs with goal of determining whether framework solves problem within unique set of constraints. Expect him to skim docs, searching for keywords related to constraints, and/or any examples similar to problem.
2) Implementation stage: Developer has settled on your framework (at least initially), and is ready to build first project. Will either complete project, or abandon framework, depending on technical quality of your docs.
These two mindsets represent two components of a sales funnel. On the docs landing page, your primary goal should be converting developers from Mindset #1 --> Mindset #2. If you look at popular docsets, you'll notice that the intro pages tend to read like sales pages. Why should you use this framework? What are some popular production implementations? Any cool examples?
Deeper in the docs, you simply need solid technical documentation. Other comments here have great tips. Just keep in mind that Mindset #1 will barely skim these areas of your docs, but will definitely consider them briefly.
So, in brief:
1) Sell developers.
2) Write good technical docs.
Here is an example of 'sales copy docs':
!!! Gets your missiles launched in seconds!
!!! Produce reports of completed strikes!
!!! Makes a great pasta salad!
!!! Provides a C library and python, perl and ruby bindings for assembling, scheduling, executing, and reporting on minuteman launch capabilities for a variety of platforms.
!!! Supports only ARM and SPARC architectures.
!!! Requires 3 active nodes on 5 different networks for high availability.
!!! No REST API support.
Sales is not dishonesty, despite the stubborn misconception commonly held by engineers. In reality, sales is the process of convincing someone that Option X is in his best interest. There should be no trickery involved. If you're a good salesman, you can convince without dishonesty.
There are honest sales techniques, too. Dishonesty is a great way to burn your long-term social capital for short-term gains. Like, how I'd phrase that is your docs should either sell developers something they end up wanting, or help build a long term relationship by pointing out that it's not something they want.
Accomplishing these "salesy" tactics while not appearing needy or shoving bullshit down someone's throat is a very fine line. The world needs more technically informed writers, and more developers should work on their writing abilities. It's a definite art / science combination that makes most technologies successful.