Using the cognitive dimensions, continued - learning style

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.