During my tenure at Microsoft I implemented and facilitated the widespread use of the cognitive dimensions analysis to assess and improve the development of Application Programming Interfaces (APIs).

An API is a collection of functions that allows two applications to talk to each other. For a company like Microsoft with an extensive and diverse developer community it is vital and imperative to get them right the first time because once an API is shipped is very difficult to fix.
When assessing APIs, developers look at their object model (OM) design (i.e. function parameters and returns, class hierarchy, etc.), security threats and so on. However, it says next to nothing about the usability of the API. How could one generate design guidelines from a usability as well as an OM perspective? The distinction between the two types of guidelines is subtle, but crucial.

OM design guidelines suggest how to design from a good software development practice (e.g. ensure there is a default constructor, abide by the “garbage collection” design pattern, etc.), but it says nothing about how users will use the APIs or what do they expect to find in one. Furthermore, APIs are developed by different teams, but one user can use those APIs concomitantly in one scenario. What is needed is a framework that can guide and assess the API design as it’s developed.