Using the Cognitive Dimensions - Penetrability

re: Using the Cognitive Dimensions - Penetrability

Woo Seok Seo — Tue, 03 Feb 2004 18:06:00 GMT

Thank you.

Very useful!

re: Using the Cognitive Dimensions - Penetrability

Frank Hileman — Thu, 05 Feb 2004 14:16:00 GMT

So the Avalon API would then require an "expansive" view, correct? The most unusable aspect of that API is the unnecessary exposure of low-level implementation details, imho.

Usually we just bag these problems all under the title "unnecessary complexity". Sometimes people break it down, and say something works at the "wrong level of abstraction." Your distinctions are very useful. However, you do not seem to have a term strictly categorizing complexity that is unnecessary.

For example, a typical design mistake is to expose several low-level details of an API implementation, simply to avoid the much harder task of figuring out an appropriate set of abstractions for the user. The usual argument is "the user needs that because of this one scenario," or more often, "performance."

But there is more than one way to skin a cat. Exposing a low-level detail may fix one problem, or solve a performance problem. But now the user is permanantly exposed to a lower level of abstraction, and the supplier must work that much harder to support upward compatability of the low-level detail. Changing the internal implementaion is no longer easy.

The better solution is often to reconsider the API at a higher level, to enable the scenario, or solve the performance problem, without exposing a low-level detail. This is much harder and developers generally prefer to skip this step, in part because it implicitly invalidates the original "architecture" (ego may be involved).

So Steve, are there terms to describe this very typical design problem? I believe it causes much unnecessary complexity in modern APIs.

re: Using the Cognitive Dimensions - Penetrability

Steven Clarke — Mon, 09 Feb 2004 17:50:00 GMT

You're right Frank, in saying that the cognitive dimensions don't describe the 'unnecessary complexity' that you talk about. Measuring the penetrability of an API on it's own doesn't really tell you much with regards to whether or not the snapshot or expansive view required by the API is reasonable.

Determining what works well is done by comparing the measurement of an API with the cognitive dimensions profile of the API user. When you look at the penetrability required to be able to use an API with that expected by a developer, you can use the cognitive dimensions framework to describe why the API is unnecessarily complex or too simple (or just right).

re: Using the Cognitive Dimensions - Penetrability

Frank Hileman — Tue, 10 Feb 2004 13:34:00 GMT

This logic doesn't sit well with me. Simply because a user can handle the complexity, does not mean the complexity is necessary. I am talking about another type of "correctness," which does not seem to be quantified or recognized in your model.

An API may provide types A and B, with numerous members on each. Or, after redesign, may provide only type C, with less members and less complexity. With C the user can accomplish everything needed; A and B were unnecessarily complex.

In API design, simplicity is generally considered one of the most important factors. Perhaps only experience in API design and the specific domain can guide one toward simplicity.

But to quantify simplicity, we must measure both functionality and complexity, and look at the ratio between them. A design with a high ratio is considered superior to a design with a low ratio. To consider a design by itself, without looking at alternatives, does not help us determine a reasonable ratio.

Any consideration of the design must include all the types in the domain area -- looking at a class in isolation does not help.

A design with a good ratio, as measured above, will tend to be more usable, because there is less mental burden, and less to learn. The books are not as thick.

Any developer can tell you their number one problem today is learning new APIs: they are proliferating rapidly, and a developer typically must be familiar with many at the same time. Since MS is responsible for much of this proliferation, API simplicity should be a top priority.

re: Using the Cognitive Dimensions - Penetrability

Steven Clarke — Tue, 10 Feb 2004 17:28:00 GMT

I should have been clearer in my response. Complexity of an API is a combination of the different factors that the cognitive dimensions framework measures. I have seen many APIs that are considered too complex by users because of the abstractions they expose (your example above), or the learning styles required to understand the API, or the working framework the API imposes, or because of any one of the other dimensions and combinations thereof.

What the cognitive dimensions framework helps expose is the reason for the complexity in the API. It helps the API designers understand in more detail why the API was too complex and what they can do to reduce the complexity. For example, one answer might be to change the abstractions so that instead of exposing a collection of primitives, a collection of factored components is exposed instead. Or, it might be that the work-step unit for many tasks is too long. In this case, the API could take care of some of the programming work required, for example automating more of the initialization required to use the API instead of forcing all that work on the user.

Additionally, all measurements have to be taken with respect to the particular user being targeted by the developer. Different users have different requirements and what might be considered complex for one user could be just right for another.

I absolutely agree with your comment about looking at alternative design ideas. It's a great point. It should be part of the design process to decribe the scenarios that the API should support and then to show multiple ways in which the API could support these scenarios. This would be a great way to identify the way that diferent design decisions impact the complexity of the API.

API Penetrability

stevencl's WebLog — Fri, 13 Feb 2004 23:13:00 GMT

Date Time Best Practices

Lance's Whiteboard — Mon, 01 Mar 2004 23:38:00 GMT