Você deve ter cuidado para evitar adicionar novo vocabulário apenas por causa da sua API. Minhas APIs favoritas me explicam coisas no vocabulário que eu já entendo. Nesse sentido:
Não adicione abstrações demais sobre o que você está construindo. Mantenha simples.
Eu já tenho que pensar em meia dúzia de camadas de abstração. Não me faça pensar em camadas extras. Não me dê muitas coisas novas para aprender que não agregarão valor ao meu objetivo final. Por exemplo, evite usar sua própria classe de arquivo especial que funcione de maneira diferente do tipo de arquivo do idioma, apenas porque você acha que seu caminho é melhor do que o geralmente aceito. Siga a maneira geralmente aceita, pelo menos em suas interfaces, para melhor ou para pior.
Ficar com idéias concretas
Por exemplo, não tente esconder o fato de que a parte "modelo" da sua estrutura MVC é um front end para um banco de dados. Aproveite o vocabulário conhecido em torno de "bancos de dados". Eu sei o que são chaves estrangeiras. Eu sei o que são linhas e colunas. Fale comigo nestes termos.
Não abstraia o conhecimento essencial
Semelhante a trabalhar com idéias concretas. Não esconda o fato de que estamos lidando com arquivos, bancos de dados ou linhas nos bancos de dados. Eu sei essas coisas. Se eu estou lidando com um contêiner, como uma Lista, há uma boa chance de eu precisar conhecer a complexidade algorítmica de operações comuns. Você pode simplificar muito dizendo apenas que é uma "lista vinculada" ou uma "matriz". De repente, um enorme conjunto de idéias será aplicado ao que você está fazendo e tudo fará sentido de repente. Não crie seu próprio conjunto de idéias que preciso aprender quando já tiver um conjunto de terminologias rico e útil para aplicar ao problema.
Reduzir o número de termos que preciso no meu vocabulário
Se estou usando sua API para abrir um arquivo de imagem de qualquer tipo, não preciso pensar muito em pngs x gifs x jpgs. Você fará isso por mim. É sua competência principal, não minha. Tenho um entendimento vago de que você tem alguma mágica para fazer isso por mim.