Here's the next howto on how to analyse an API using the cognitive dimensions framework. As always, your comments are much appreciated!

 

For each user goal that the API supports, describe the minimum understanding of the API that the user needs in order to accomplish that goal. The minimum understanding lists the classes or components that the user needs to work with to accomplish their goal and the explicit dependencies each of those classes has on other classes.

 

For example, if the goals are to append a line of text to a file and read a line of text from a file using the System.IO classes, the minimum understanding of the API might be described as:

 

  • Users must know that they need to use an instance of StreamWriter to append text to a text file.
  • Users must know that they need to use an instance of StreamReader to read from a text file.
  • Users must know that the StreamWriter and StreamReader classes are defined within the System.IO namespace.

 

Having described the minimum understanding of the API required, you can now define the learning style of the API in the following terms.

 

  • If each scenario requires a small number of classes and each of those classes have a small number of dependencies on other classes then the API supports an incremental and minimal learning style. In other words, users only ever need to know about the parts of the API that are relevant to their goal and they can acquire this understanding bit by bit.
  • If each scenario requires a large number of classes and each of those classes have a large number of dependencies on other classes then the API supports (or demands) a top-down or structured learning style. In other words, before being able to do anything useful with the API, the user needs to gain an understanding of the different components exposed by the API, the dependencies between different components exposed by the API, the architecture holding the API together and other conceptual information.

 

Given the above definition, the System.IO classes support a learning style that is close to minimal and incremental. Users can explore the types exposed by the namespace and use or examine each one independently of other types.

 

APIs that support minimal and incremental learning support exploratory programming, allowing the user to write a couple of lines of code to try to get something working and build up an understanding of the API from that experience. APIs that support a top-down, or structured learning style generally demand that users read a high level overview of the API first and only start writing code once they have an idea about the architecture of the API and how each class in the API relates to other classes in the API.

 

Different users prefer different learning styles. Some users don’t want to have to learn about the API at a high level before they can start working. Other users like to be able to get such a high level overview of an API so that they can form a mental model of the whole API and make the most effective and efficient use of that API. It is important to ensure that the learning style preferred by your users is supported by the API.

 

Note that learning style is not necessarily mutually exclusive. For example, an API might support both incremental and top-down learning styles. But if it only supports one particular learning style, that style must be the same as the learning style preferred by the intended users of the API.