How do I write documentation?

A client asked me this very question today....

This was one of the first things that I learnt, did, and like to think that I did rather well.  My take is that you, as a developer, are not only writing documentation. You are also writing sales copy for your framework.

Recognize that developers will come to your API docs with two possible mindsets:
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.

Write well, code better.