Freigeben über

Using the cognitive dimensions framework to design usable APIs

  • Artikel

A few weeks ago, I posted some
details about the cognitive dimensions framework that we use at Microsoft when considering
API usability. Up to now, we've been using it primarily to describe the results of
studies done on APIs in our labs. What I'd really like to see though is different
API teams being able to use the framework as a means to design an API, rather than
evaluate it. Over the last couple of weeks I've been writing up a document that guides
API teams in evaluating whether or not their API design is progressing in the direction
they would like it to, with respect to the framework. I thought I would share
this with you. I'm hoping that you'll be able to provide good feedback on this approach
so that I know whether or not this really is useful for teams designing an API.

The basic idea is to start the design of an API by describing the type of developer
that the API is designed for in terms of the cognitive dimensions framework. For example,
your customer might be a developer that prefers APIs that expose a set of aggregate
components, that prefers an API that supports a bottom up learning style etc
etc. Then, for each scenario that the API is designed to support, write the code that
the developer will have to write using the API to implement that scenario. Note that
you can do this before you're anywhere near ready to start implementing your API.
Just write out the code in a text editor - what you are doing is saying 'When the
API is ready, here is the code that we would like developers to write when tackling
this scenario'. It's sort of like designing a UI for a product before implementing
the product. Designing an API and a GUI in this manner (from the perspective of the
user) means that it is less likely that the implementation details of the product
will surface in either the GUI or the API.

Once you have a set of code samples, you can then start to evaluate them in terms
of the framework.

Let's begin by looking at how we might evaluate the abstraction level dimension. We
start by doing a task analysis of
each of the scenarios.

For each user goal that the API supports, describe the tasks that the user has to
implement to accomplish that goal. For example, in the System.IO namespace one goal
might be to append a line of text to a file. For such a goal, the list of tasks might
be:

"urn:schemas-microsoft-com:office:office" />

 

-
Open the file with a given name

  -   
    Create the file if it does not already exist

  • Write a line of text to the file

  • Close the file

     

Note that a task analysis for an API describes the different actions that a developer
would expect to have to accomplish. It does not describe how the API supports these
goals. For example, one API might create a file automatically if you attempt
to open a file that does not exist, another API might force the developer to
explicitly create the file. They both support the same action from the developer's
perspective, they just support it differently.

 

For each task that you describe in each goal, list the different API components that
are involved in accomplishing that task. For example, to open the file in append mode,
you might create an instance of the StreamWriter class and set the append parameter
to true in the StreamWriter constructor. The StreamWriter constructor will create
the file if it does not exist so there is no extra action to be taken to create the
file. To write to the file, you would then call StreamWriter.Write or StreamWriter.WriteLine
using the instance of the System.IO.StreamWriter class returned by the constructor.
You would then finish off by calling StreamWriter.Close.

 

Do a similar task analysis for each goal that the API supports. For example, an additional
goal for the System.IO classes might be to read a line of text from a file. In this
case, the tasks would require the use of the StreamReader class in order to open,
read from and close the text file.

 

Having described the different tasks that the user has to accomplish to achieve each
goal and the different components that the user has to use to implement each task,
you can now describe the nature of the components in the following terms.

 

- If individual tasks require two or more components to be used in conjunction, the components are considered primitives. In other words, individual components exposed by the API do not map on to unique user tasks.

If each individual goal requires the use of only one component, but the set of goals  
requires different components, the components are described as factored components.
  • If the set of goals could all be accomplished with the same set of components, the
    components are described as aggregate components.

Given the above definition, the System.IO classes are best described as factored components
since each goal requires the use of different components (StreamWriter to write to
a file and StreamReader to read from a file). Each class is factored to a particular
goal, but different components are required to achieve different goals.

Do
the above analysis for each scenario that your API supports. If each scenario that
your API supports is likely to be accomplished by the same type of user, you should
attempt to ensure that each scenario exposes the same type of abstractions. If each
scenario that your API supports is likely to be accomplished by different users, you
should attempt to ensure that each scenario exposes the type of abstractions that
those users are most likely to be successful and comfortable with.

Given
the above analysis, if the target customer for System.IO prefers to work with factored
components, this indicates that the design will satisfy them with respect to this
dimension.

We'd
complete the analysis by looking at the other dimensions in turn. I'll describe how
to analyze the remaining dimensions in later postings.

Comments

  • Anonymous
    November 15, 2003
    The comment has been removed
  • Anonymous
    November 16, 2003
    The comment has been removed
  • Anonymous
    August 18, 2010
    Parallel programming is difficult. No surprises there really. I came across a great slide deck discussing