Using the cognitive dimensions – working framework


 

The next installment in using the cognitive dimensions…

For each user goal that the API supports, describe the minimum amount of information
that the user needs to maintain while working with the API. This is different to the
learning style which refers to the way that the user gains the information they need.
Working framework describes the amount of information that they need.

"urn:schemas-microsoft-com:office:office" />
 

In the System.IO example, the user must keep track of the following information:

 

  • The mode in which the instance of the StreamWriter class the user is working with
    has been opened in, so that they know whether or not the file will be created if it
    doesn’t exist, whether or not the file contents will be appended or overwritten etc.
  • The structure of the text file, if it is a structured text file. In other words, the
    code that the user needs to write in order to read from or write to a structured text
    file will depend on the structure of that text file.
  • The actual file that the instance of the StreamWriter or StreamReader refers to.

 

In this case, much of the information that the user needs to keep track of is represented
in the API that the user uses to accomplish the goal. For example, the mode of the
StreamWriter or StreamReader is a property of the instance of the class the user is
working with. However, the structure of the text file is not directly represented
by the API. In order to use the System.IO classes to work with a structured text file,
the user needs to maintain some application level information.

 

Having described the information that the user needs to keep track of for a given
set of goals, the working framework can be defined in the following terms.

  • If the information that the user needs to maintain is represented in the API that
    the user is using to accomplish some goal, the working framework is described as local.
  • If the information that the user needs to maintain is not directly represented in
    the API that the user is using to accomplish some goal, but is represented in the
    way that user code is structured, the working framework is described as global.
  • If the information that the user needs to maintain is not represented at all in the
    API or the code that the user is writing to accomplish some goal, the working framework
    is described as system.

Given the above definitions, the System.IO namespace classes require a working framework
close to global for all but the simplest of tasks. 

Different
users can tolerate different working framework demands placed on them by an API. Make
sure that your API does not demand more than your users will tolerat

Comments (2)

  1. Frank Hileman says:

    Could you clarify the "system" working framework a bit. Does it mean, using other namespaces? Or internal state from internal global or static variables (static in the C# sense, shared)? If the information is not maintained in the code or the API, then where might it be?

  2. Steven Clarke says:

    If an API requires that a developer makes use of APIs defined in other namespaces, or needs to create and maintain internal or global variables to be able to use the API, this would be a good example of an API that demands a working framework that is somewhere between global to system level.

    An example of a system level working framework would be when you’re using an API to retrieve data from a database and the database schema is not represented in the API (e.g., such as when using untyped datasets). In this case, you have to keep in mind the schema of the data you are working with.

    APIs that have a system level working framework offer certain advantages – for example, they may be more loosely coupled to components that they depend on than APIs that have more of a local working framework. In the case of the untyped dataset, they offer the flexibility that you can work with data for which no known schema is available until you actually retrieve the data or when working with data that has a dynamic structure.

    Some developers prefer the flexibility and power offered by APIs that have a system level working framework while others may trade off flexibility and power if it means they do not have to concern themselves so much with the details of other components that their code depends upon.