I am working on an application for which a rich plugin API is crucial. What is the best process for creating an API that is intuitive and easy to learn?
What is the best process for creating an API that is intuitive and easy to learn?
First, create an API that works.
Then, after using it for a while, get feedback on the parts that are not intuitive or easy to learn.
Third, rewrite the API to be more intuitive and easier to learn.
Then, after using the revised API for a while, get more feedback on the parts that are not intuitive or easy to learn.
When you get to the 3.0 rewrite of the API to be more intuitive and easier to learn, you may actually have something that works.
This is very, very hard to do "out of the box".
It takes experience, and -- more importantly -- it takes a lot of back and forth between the producers and consumers of the API's.
Until you know your users, you have a lot to learn about them and what amounts to "intuitive" and "easy to learn".
Most API's don't really strive for this. They strive for "efficient" or "simple" or something that's much easier to achieve.
Here's the point.
"Intuitive" and "easy-to-learn" are very personal attributes. What is intuitive for one person is stupid to another. What is easy to learn for one person is baffling to another.
You can't achieve "Intuitive" and "easy-to-learn" without knowing your users really, really well.
You can't know your users really, really well until you interact with them by providing them an interface, which they use, and then you get detailed feedback on their experience.
Learning about your users takes a lot of back and forth between you and them.
You must make active steps to learn about your users so that you know what constitutes "intuitive" and "easy-to-learn". When your users argue amongst themselves, you'll learn a lot about what "intuitive" really means. [Hint: it means nothing.]
One easy way to take active steps to learning about the users is to cycle through several releases. There are other ways to learn about your users.
Look for existing Plugin APIs. I whould recommend Eclipse (based on Extension Points) and Netbeans (based on Lookups). Well, it also depends on to what extent you wish the plugins to extend your application. In Eclipse, you can change virtually every aspect of the application. We are using Extension Points approach in our GWT application. Another good architectural pattern for plugins is the Chain of Responsibility.