Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

2 Answers 2

up vote 6 down vote accepted

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.

share|improve this answer
    
Using APIs that achieve a similar goal might also be useful. –  Mahmoud Hossam Apr 18 '11 at 21:21
    
@Mahmoud Hossam: isn't that advice essentially the same as the @Dmitry Negoda answer? –  S.Lott Apr 18 '11 at 21:26
    
yeah, sorry, I wasn't paying attention. –  Mahmoud Hossam Apr 18 '11 at 21:30
    
So, in other words: iterate. –  S W Apr 18 '11 at 23:34
    
@S W: Close. But, no. "Iterate" is not a good one-word summary. I hate to repeat the entire answer in the comments, but I'll change the emphasis so that "iterate" is not the answer. –  S.Lott Apr 19 '11 at 9:51

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.

share|improve this answer
    
I have bad memories of Eclipse's plugin APIs, juggling XML files, etc. I will take another look though, I was a newer programmer then. –  S W Apr 18 '11 at 17:37
    
Wouldn't looking at a strongly typed, offline app not quite make sense for a javascript based API? –  Wyatt Barnett Apr 18 '11 at 19:06
    
Netbeans (based on Lookups)? I am not a java prorgammer, but isn't that based on an implementation of an interface/inherited base class. Which kind of is very similar to extension points? –  Cohen Sep 20 '11 at 10:19

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.