this is a good description of the individual concerns, but it's missing a really important consideration that most API designers seem to ignore: what's the idea

this is a good description of the individual concerns, but it's missing a really important consideration that most API designers seem to ignore: what's the ideal way (or ways) for someone to use your API? once you have some answers to that, you can start designing an onramp to your API that subtly guides developers towards the kinds of idioms that you want them to learn. it's not just a matter of following the right form in the right example, but overall organization--what concepts are introduced as being related, the kinds of examples you have at all, etc.