Debes tener cuidado de evitar agregar vocabulario nuevo solo por tu API. Mis API favoritas me explican cosas en vocabulario que ya entiendo. Entre esas líneas:
No agregue demasiadas abstracciones sobre lo que está construyendo. Mantenlo simple.
Ya tengo que pensar en media docena de capas de abstracción. No me hagas pensar en capas adicionales. No me des muchas cosas nuevas para aprender que no agreguen valor a mi objetivo final. Por ejemplo, evite usar su propia clase de archivo especial que funcione de manera diferente que el tipo de archivo del idioma solo porque cree que su forma es mejor que la forma generalmente aceptada. Quédese con la forma generalmente aceptada, al menos en sus interfaces, para bien o para mal.
Seguir con ideas concretas
Por ejemplo, no intente ocultar el hecho de que la parte "modelo" de su marco MVC es una interfaz para una base de datos. Aproveche el vocabulario bien conocido que rodea a las "bases de datos". Sé lo que son las claves foráneas. Sé lo que son las filas y columnas. Háblame en estos términos.
No abstraiga el conocimiento esencial.
Similar a trabajar con ideas concretas. No oculte el hecho de que estamos tratando con archivos o bases de datos o filas en bases de datos. Yo se estas cosas. Si estoy tratando con un contenedor, como una Lista, hay una buena posibilidad de que necesite conocer la complejidad algorítmica de las operaciones comunes. Puede simplificar mucho eso simplemente diciéndome que es una "lista vinculada" o una "matriz". De repente, un gran conjunto de ideas se aplicará a lo que estás haciendo y de repente todo tendrá sentido. No cree su propio conjunto de ideas que tengo que aprender cuando ya venga con un conjunto rico y útil de terminología para aplicar al problema.
Reduce la cantidad de términos que necesito en mi vocabulario
Si estoy usando su API para abrir un archivo de imagen de cualquier tipo, no debería tener que pensar mucho en pngs vs gifs vs jpgs. Harás eso por mí. Es tu competencia principal, no la mía. Tengo una vaga comprensión de que tienes algo de magia para hacer esto por mí.