Using the cognitive dimensions - domain correspondence

  • Article

This is the last in the series I've been posting about how to use the cognitive dimensions framework to evaluate your own APIs.

For each user goal that your API supports, describe how closely related the classes and methods exposed by the API are to the conceptual objects that users think about manipulating when using the API.

 

In the System.IO namespace, a user goal might be to append text to a text file. In order to accomplish this task, users need to use the StreamWriter class to manipulate the contents of a file on disk. For some users, this might not be obvious. Some users might expect to find a type that more closely represents a file on disk such as a File or FileObject class. The concept of streams used by the StreamWriter class might be unfamiliar to these users. They may be put off from using the StreamWriter class since it does not map well to the corresponding domain.

 

Domain correspondence can be defined in the following terms.

 

  • If the types exposed by the API map directly on to the types and concepts expected by users, the API is said to have a direct domain correspondence.
  • If the types exposed by the API only map on to the types and concepts expected by users after describing the mapping, the API is said to have a plausible domain correspondence.
  • If the types exposed by the API do not map directly on to the types and concepts expected by users even after describing the mapping, the API is said to have an arbitrary domain correspondence.

Given the above definition of domain correspondence, the System.IO namespace class has a plausible domain correspondence. For some users, the mapping from a stream based type to a physical file on disk will need to be explained. Once explained however, the user will then be able to work with the type as it exposes familiar methods such as Write and WriteLine which map well on to the methods that users would expect in this domain.

I just need to find a way now to link to each of the postings for easy access...