Using the Cognitive Dimensions - Work Step Unit

Continuing my series of posts on using the cognitive dimensions framework. I have a few to catch up on...here's the next on how to evaluate the work step unit for your API.

 

For each user goal that the API supports, describe the tasks that the user has to implement to accomplish that goal. For example, in the System.IO namespace one goal might be to append a line of text to a file. For such a goal, the list of tasks might be:

 

• Open the file with a given name
  • Create the file if it does not already exist
• Write a line of text to the file
• Close the file

 

Then, for each task, describe the amount of work that the user has to do to accomplish each task. Describe the amount of work that the user needs to do in terms of its scope and in terms of the progression from starting the work to completing the work. For example, does the work involve a few lines of code added to one code block or scope, or does it involve the creation of multiple classes throughout the application code. In the case of using StreamWriter to append a line of text to a text file, the work step unit involved for each step might be described as follows:

 

Step	Work involved
Open the file with a given name	Create an instance of StreamWriter. Pass the path to the file and the append property as parameters. Scope of work is local to the module in which the StreamWriter will be used. There is a linear progression from start to end, since there is only one line of code required.
Create the file if it does not already exist	No extra work involved since the above step will take care of this.
Write a line of text to the file.	Call StreamWriter.WriteLine and pass the string to write as a parameter. Scope of work is local to the module in which the StreamWriter will be used. There is a linear progression from start to end, since there is only one line of code required.
Close the file	Call StreamWriter.Close. Scope of work is local to the module in which the StreamWriter will be used. There is a linear progression from start to end, since there is only one line of code required.

 

Having described the work step unit for a user goal, the work step unit for the API can be described in the following terms.

 

• If the code that users have to write to accomplish a task using an API is completely contained within one local code block, and the code required can be written incrementally, the work step unit is defined as local incremental.
• If the code that users have to write to accomplish a task using an API is contained within multiple code blocks, or if the code requires the instantiation of multiple classes that interact, the work step unit is defined as parallel.
• If the code that users have to write to accomplish a task using an API is neither local or parallel but somewhere in between, the work step unit is defined as functional.

 

Given the above definition of work step unit, the System.IO namespace exhibits a local and incremental work step unit when writing code to read from or write to a text file.