The Visual Studio usability group at Microsoft, of which I'm a part, is responsible for helping design and build the user experience for developers using Visual Studio and the .NET platform. Much of our efforts at improving the developer experience have focused on improving the usability of the Visual Studio development tool itself. For example, we run extensive empirical studies in usability labs focusing on particular features of Visual Studio (such as the debugger), gathering data to help feature teams improve their designs. In this way, we can understand how best to present complex information, such as the structure of application data, to support developers better when they are debugging code.
But while improving the design of Visual Studio is a necessary component of improving the developer experience, it is not sufficient. The development tool is only one tool that developers routinely use when building applications. The other major tools are the programming language they are coding in (C++, C#, VB, and so on) and any class libraries or APIs that they are coding against (MFC, .NET Frameworks, and the like). The usability of the languages and libraries that developers use have a significant impact on their ability to successfully complete a set of development tasks. In this article, I describe some of the techniques we use to design and evaluate the usability of the APIs that ship with .NET, and discuss ways in which you can use them for APIs you are designing.
Usability Applied to APIs
Most of us know what usability means when applied to software with graphical user interfaces (GUIs)—developer tools, word processors, or e-mail clients. We expect these tools to let us perform a given set of tasks and to work the way we expect them to. If I'm using a visual debugger, for example, I expect to be able to examine the state of a variable at some point during the execution of my code. I expect to be able to do this by using some debugger tool window that shows a list of variables that are currently in scope and selecting the variable that I want to examine. Or, if I am checking my e-mail, I want to see the new, unread e-mail that has arrived since I last read my e-mail. I expect to be able to do this by opening the client and having the new e-mail displayed in a way that distinguishes it from the old e-mail that I have read. If any of the products that we use fail to work in the way that we expect them to, we generally label this as poor design or usability.
There can be many causes for poor product usability or design; for example, users may not be aware of the actions that they can take with a product. Likewise, they may not be able to predict the result of performing some action and hence might be reluctant or less inclined to perform that action for fear of the potentially negative consequences that might ensue. Or they misinterpret the actions that they can take and the results of those actions.
Psychologists use the term "affordances" to refer to the actions that a user can take on some object. However, just because an object "affords" some action, it doesn't mean that the user will realize that they can take that action—users have to be able to perceive the affordances exposed by some object. Many usability breakdowns that occur in GUIs are due to affordances not being perceived by users. For example, for some users, the Start button in Windows XP is not perceived to afford the action of shutting the computer down.
Likewise, APIs expose affordances. Every API has a set of actions that it can perform. Therefore, usability problems can exist in an API that are related to users not perceiving the affordances the API supports. For example, an API for performing file I/O might afford creating a new file, writing to a file, reading from a file, deleting a file, copying a file, and moving a file; see Example 1.
class FileIO
{
public FileIO(string path){...}
protected ~FileIO(){...}
public void Close() {...}
public void WriteLine(string text) {...}
public string ReadLine(){...}
public void DeleteFile(){...}
public FileIO CopyFile(string newPath) {...}
}
Example 1: API for simple file I/O.
However, developers browsing the public interface of this API might not perceive the complete set of affordances that this API offers. In particular, they might not realize that they can use this API to move a file from one location to another by copying the file, then deleting the original. Or they may not realize that the constructor creates a new file, if the path specified in the constructor does not already point to an existing file.
Designing Usable APIs
One of the best ways to design usable GUIs or APIs is to follow a user-centered-design approach. User-centered-design encompasses understanding both your users and the way that they work in the scenarios the product is designed to support. Application implementation details do not drive the design of the user interface and should not be represented in the interface design. Instead, the design should reflect the way that users expect to work.
Designing usable APIs is similar to designing usable GUIs. You must make sure that you understand the characteristics of users and how those characteristics impact the way they expect the API to work. Following a scenario-based design approach ensures that the API reflects the tasks that users want to perform, instead of reflecting the implementation details of the API.
We follow a scenario-based design approach for all of our APIs. For each API, we write a collection of code samples that show how to use the API in a set of given scenarios. The API design then proceeds in such a way that it supports developers in writing these code samples. If a particular design decision makes it more difficult for developers to write the code contained in one of the samples, that decision is carefully reviewed. Additionally, APIs are reviewed periodically by examining the code samples and determining whether or not developers would be comfortable writing the code in each of the samples.
Just as for GUI design, scenario-based design for an API must start from some characterization of users. If the API design starts out with invalid assumptions about how developers write code, then the API will be less likely to work the way that developers expect it to. Instead of exposing the set of types and methods that developers will be expecting, it exposes a different set of types and methods whose purpose may not be so clear and that may be difficult to use. We use a framework known as the "cognitive dimensions" to describe the characteristics of developers that have an impact on the usability of an API.
Cognitive Dimensions
The cognitive dimensions framework presents a set of 12 different dimensions (or factors) that individually and collectively have an impact on the way that developers work with an API and on the way that developers expect the API to work. These dimensions are the:
- Abstraction level. The minimum and maximum levels of abstraction exposed by the API, and the minimum and maximum levels usable by a targeted developer.
- Learning style. The learning requirements posed by the API, and the learning styles available to a targeted developer.
- Working framework. The size of the conceptual chunk (developer working set) needed to work effectively.
- Work-step unit. How much of a programming task must/can be completed in a single step.
- Progressive evaluation. To what extent partially completed code can be executed to obtain feedback on code behavior.
- Premature commitment. The amount of decisions that developers have to make when writing code for a given scenario and the consequences of those decisions.
- Penetrability. How the API facilitates exploration, analysis, and understanding of its components, and how targeted developers go about retrieving what is needed.
- API elaboration. The extent to which the API must be adapted to meet the needs of targeted developers.
- API viscosity. The barriers to change inherent in the API, and how much effort a targeted developer needs to expend to make a change.
- Consistency. How much of the rest of an API can be inferred once part of it is learned.
- Role expressiveness. How apparent the relationship is between each component exposed by an API and the program as a whole.
- Domain correspondence. How clearly the API components map to the domain and any special tricks that the developer needs to be aware of to accomplish some functionality.
The framework is used to describe both what a given set of users expect from an API and what the API actually provides. For example, we can describe the abstraction level that users expect to be exposed by an API and can compare this with the abstractions actually exposed by the API. It's the comparison between what developers expect and what the API provides that is interesting when evaluating the usability of an API. If there is a good match on each of the dimensions, we can feel reasonably confident that the API will meet the needs of that particular type of developer. However, if there are significant differences between what the API exposes and what the developer expects, we can concentrate on improving the API in the particular areas where differences exist.
To do such a comparison, we normally run a usability study in our usability labs. In a usability study, we ask a group of developers to use the API to perform a set of tasks. The tasks that the developers work on in the usability study are designed in such a way that they expose those areas of the API in which we are most interested in gathering feedback. Typically, the tasks relate to the main scenarios that the API is designed for; but sometimes, we focus on a specific area of the API to get detailed feedback on that one area.
After the study, we spend time reviewing the data. We look for patterns of behavior across all of the participants, whether they are patterns that led to success or failure on tasks. If the pattern led to success, we want to make sure that the API team is aware of the particular aspect of the API design that was responsible so that the successful design can be reused when appropriate elsewhere. If the pattern led to failure, likewise, we want to make sure that we do not repeat the same mistakes elsewhere in the design. In both cases, we use the cognitive dimensions framework to analyze and describe the results of the study.
