Even More Wisdom on Designing Usable APIs

If you saw the last piece, I was attacked and almost lynched by a mob of JINI zealots. Actually, I exaggerate, what's paradoxical is that I had quoted the designer of JINI in several earlier entries on usable API design¹. It appears that I may be in conflict, apparently simplicity and elegance are only tangentially related to usability. So, I did a bit more "googling" to get clarity.

Of course, there's no better place to learn about usability than Jakob Nielsens site. As I wrote earlier, APIs are also a human factors problem, so Nielsens thoughts on UI usability should be quite applicable. So here's an important definition I dug up:

I usually promote usability, but truth be told, a better model is to analyze the usefulness of a service which is a combination of two parameters:

1. Utility: what does the service do; how closely does it match users' needs
2. Usability: how easy, efficient, and pleasant is it to use the service

Both are necessary: If a system has no utility, it doesn't matter how easy it is to learn or how efficient it is to use (50 irrelevant transactions per hour remains a useless exercise). But even the highest utility is for naught if users cannot figure out how to use it.

That's better, the minimal API that JINI provides are quite powerful, however this just addresses one part of the equation, that is of utility. However, not many people have figured out how to use it, which should be a glaring indicator of its usability issues.

Researchers at Microsoft have an even more complex approach to defining usability for APIs. They've dubbed it "Cognitive Dimension Analysis". From a set of 12 dimensions:

they've developed three developer personas (Opportunistic, Pragmatic and Systematic). The skinny is that APIs tend to work better when they closely match a personas and ultimately its working style. Now, I'm not a psychologist and because this is coming from Microsoft it could be a whole lot of "mumbo jumbo", however its pretty clear, one API doesn't fit all. That's the biggest mistake many make, trying to mold one perfect API. You have to consider several to match the needs of you varying audience. Of course, if the audience is only you, well then maybe you should take up some "Character Acting" classes

This reminds me of the earlier piece I did on thinking styles and programming languages, but even within the same programming language you wear a different hat. The "Analyst" values performance, the "Idealist" values elegance, the "Pragmatist" values ease of use and as expected the "Realist" would scream YAGNI! Try balancing all these personas inside your own head and even harder amongst your team members.

So when you talk about the "usefulness" of an API, you have to think utility, usability and target audience. There lies the crux of the problem in Java APIs, the target audience is a bunch of analysts and idealists, the pragmatists and realists can all rot in hell playing with their simpleton devices.