I would go as far as saying that if your API requires familiarity with "general patterns" and "background knowledge" you probably have done a bad job designing

I would go as far as saying that if your API requires familiarity with "general patterns" and "background knowledge" you probably have done a bad job designing it. Your API has a purpose. It does things. I know what that is, that's why I came here to use your API. I can verbalize what I want your API to do for me, and that is what I will search for. I will not look at your whole documentation, I do not care about your general concepts. All your ideas about architecture and design stand between me and my goal. I want you to apply the principle of least astonishment. If there's something non-obvious that might cause issues, mention it in all the places where it applies. Yes, this goes against your urge to not repeat yourself. Do not give in to these urges. Sometimes people design APIs with great flexibility in mind, requiring you to assemble a great many parts in the right shape to achieve your goal. This is almost certainly not what the user wants. If you intend to design such an API, use the "layered" approach. At the top, there should be the most common functionality, as obvious as possible, with as little configuration as is reasonable. This is the layer that almost everyone will need - and not more. This layer is implemented using the more flexible layer below.