Using the cognitive dimensions - premature commitment

  • Article

After a long absence, here's the next installment in a series on how to use the cognitive dimensions framework.

For each goal that the user will attempt to accomplish with the API, list the alternative ways that the API allows the user to accomplish that goal and describe the information that the user needs in order to be able to decide which alternative to choose. Then describe how obvious it is to the user that they have a choice to make and any issues that this might cause users.

 

For example, in the System.IO namespace, one goal might be to write code to append text to a file. The user has at least two different ways that they can accomplish this task.

 

  1. The user can create an instance of a StreamWriter and set the append parameter in the constructor to true so that text will be appended to the file.
  2. The user can use the static File class to call AppendText which creates an instance of a StreamWriter that will append text to the contents of the file.

 

It is not necessarily obvious to the user that they have a choice for this goal. For example, the documentation for the API provides many code samples that demonstrate the first alternative but fewer samples that demonstrate the second alternative. Exploring the classes exposed by System.IO doesn’t identify the existence of a choice either since the names of the classes, File and StreamWriter seem somewhat unrelated (if File had been called StreamCreator then the existence of a choice would perhaps have been more obvious).

 

However, it is not likely that users will experience significant problems, due to being unaware of the different ways to create a StreamWriter. Regardless of the method chosen, users will end up creating a StreamWriter that they can use to append text to a text file. There is no difference between either approach in terms of the final result.

 

Premature commitment can be defined in the following terms

 

  • If the API presents the user with a small number of choices about how to accomplish some goal and if the differences between any alternatives are minimal, the API exposes minor and reversible level of premature commitment.
  • If the API presents the user with a significant number of choices about how to accomplish some goal and if the differences between the alternatives are minimal, the API exposes significant and reversible level of premature commitment.
  • If the API presents the user with a significant number of choices about how to accomplish some goal and if the differences between the alternatives are significant, the API exposes a significant and irreversible level of premature commitment.

 

Given the above definition of premature commitment, the System.IO namespace exhibits premature commitment close to minor and reversible.