Interface User

Find my posts on IT strategy, enterprise architecture, and digital transformation at ArchitectElevator.com.

We often consider user interface design to be related to graphical or text-based interfaces where users enter data, select from menu items and drop-down lists, or click hyperlinks. There are many good books on user interface design, both in terms of the aesthetic aspects as well the process of usability studies and task analysis.

One user group that is all too often forgotten from the usability effort, however, are other programmers. Programmers are clearly users of code: they code against your classes or interfaces or might access your Web services remotely. And all too often they struggle with the same issues end user do: which function to execute first, confusion over unclear error messages, uncertainty over the meaning of a specific field, mismatches between the users mental model and the (user) interface model just to name a few.

Just as I was thinking of rambling on this topic of programming interface usability I discovered Ken Arnold's excellent article Programmer's are people, Too in ACM Queue Magazine (unfortunately, the full version requires ACM on-line library access). Alas, it turns out that his interest in this topic is by no means recent -- I just never happened to stumble on his work. He actually shared a number of the same thoughts in an Interview on Artima quite a while ago. So I won't plagiarize his work here but just give some of the highlights and add my personal views on the topic.

Why is this topic worth highlighting on a blog about enterprise integration? Programming interface usability issues are often minor as long as the "programmer user" is on the same team (or even the same person) as the creator of the code and the number of potential users is small. However, if you are developing a code library or a published service, your users might be far away or might want to access functions even after the original developer might have left the company. With the increasing popularity of Web services a lot more programming interfaces of sorts are being exposed to an ever-increasing number of developers. This naturally increases the concerns of usability.

What Makes an Interface Usable?

A number of usability considerations match good common design guidelines for interfaces:

• Good, descriptive field and operation names.
• Consistent naming in both word choice and sequence. For example, one can easily think of least the following names for a simple operation: StartOperation, BeginOperation, OperationBegin, OperationStart, OpStart, and so on. If you want to make your interface users happy, choose one style and use it consistently.

Other design aspects are more subtle and more directly related to usability:

• Progressive Disclosure - when you look at successful end-user software such as MS Office or Star Office, the key feature that tends to stand out is that of progressive disclosure. My mom uses Word even though she is familiar with maybe 5% of the features. I use Word as well but probably use 50% of the features. Magically the software adapts to either usage scenario because advanced features are available but do not stand in the way of simple usage. Unfortunately, this approach is rarely used in the design of programming interfaces. You usually get a list of umpteen functions, most likely in alphabetical order. This gives a user very little guidance as to where to get started.
• Common Patterns - following a common design pattern increases the chances that the reader can quickly grasp how the interface functions. Every so often, readers lament that books on design patterns contain material that they already knew. Nevertheless, having a catalog of named patterns allows many developers to talk about the same concept by the same name. I have experienced this many times where after hours of discussion one developer shouts out "oh, what you mean is an xxx'. This benefit extends to the design of programming interfaces. I hope that my work on conversation and interaction patterns will be particularly helpful in this area.
• Executable Test Cases - one of the most useful aids in helping someone how to use an interface is to provide a suite of executable test cases that can both serve as example code as well as a precise description of the observable behavior of the component at hand. If your interface is available across platforms, this can be a little harder to do because test cases provided in one programming language might not be useful to all developers. However, the behavior of a Web service could be described by a set of matching input and output documents (assuming the service follows a request-response interaction model).
• Forcing Functions - the best usability guides are devices that keep users from making simple mistakes by prescribing a logical sequence and enforcing it. For example, you won't get you money out of the ATM until you remove the card -- making it nearly impossible to forget your card (unless you do not care about picking up your cash!). This function became particularly clear to me when I walked up to an ATM and the machine put someone else's card right into my hands. The person had deposited money and the machine does not have a similar forcing function for deposits. In the world of programming interfaces, strong typing can help in this regard. If one operation requires a type that can only be obtained by one (or a few) other operations, the expected sequence of operations is implicitly enforced. if all parameters are strings and ints then it is hard to guess what should happen in what order.
• Affordances - similar, but different are affordances. Affordances are cues as to the usage of an object. A round door know suggests to turn it, a handle suggests pulling, and a bar suggests pushing. We can use similar approaches with methods and operations.

There is a lot to be said about the usability of programming interfaces. For an entertaining and enlightening insight into the world of usability I highly recommend Don Norman's Design of Everyday Things. And thanks again to Ken Arnold for inspiring me to finally write this up.