- be meaningful. listWidget(str name): Returns a Widget is useless to me. 90% of api docs i see are like this, its evident they've been auto-generated and no effort had been made. Code samples help but really they are second order answers to the fundamental questions users have: why should I consume this function? How do I consume it? What should I expect? How to detect problems? And, hardest of all, when should I use something else?
- include an overview block at the start of every api definition, to orient the reader. What does this API do? What are the most important objects and calls? What limits and rules does the reader feed to know? Write at a lower reading level than you normally use to capture newbies and non native speakers.
- Meaningful code samples are great, but dont kid yourself. If the sample is unrealistic, particularly if you are eliding a difficulty that the real world practictioner is guaranteed to face, you are cheating yourself and them. Address it.
- make navigation easy. breadcrumbs, scroll to top, cross refs etc.
I've never found api docs that hit all of these, by the way.