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:
Having described the minimum understanding of the API required, you can now define
the learning style of the API in the following terms.
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.