Channel 9 just posted a video in which our API usability engineers talk about one of the studies they conducted recently, but what’s even more interesting, in part two of the story, they show a clip from an actual study where a participant writes a workflow application. This is big! We have tried to release usability clips publicly for a very long time and for various reasons it was difficult to do.

I always thought that a good collection of clips (short 1-3 minute clips cut from long usability videos) illustrating tradeoffs involved in API design would be of great interest outside Microsoft and a great teaching and research tool. Ultimately, I would love to have each guideline linked to a video illustrating the point. Hint: please bug Steven and Charles (channel 9) to release more videos like that :-)

We use such clips internally when we teach API design, and as they say a picture is worth a thousand words. Many design guidelines are actually quite unintuitive to domain experts who design the APIs (for non-experts). Brad and I feel very passionate about the making sure that API designers really understand the user, and that they don’t assume that the user is just like them. Here is what we wrote in the Design Guidelines book (a guideline and two annotations):

Do understand the broad range of developers using multilanguage
frameworks.

KRZYSZTOF CWALINA It is easy to design for users who are like
you, and very difficult to design for somebody unlike you. There are too
many APIs that are designed by domain experts and, frankly, they are only
good for domain experts. The problem is that most developers are not, will
never be, and do not need to be experts in all technologies used in modern
applications.

BRAD ABRAMS Although the famous Hewlett-Packard motto “Build
for the engineer at the next bench” is useful for driving quality and completeness
into software projects, it is misleading for API design. For example,
the developers on the Microsoft Word team have a clear understanding
that they are not the target customers for Word. My mom is much more the
target customer. Therefore the Word team puts in many more features that
my mom might find helpful rather than the features the development team
finds helpful. Although that is obvious in the case of applications such as
Word, we often tend to miss the principle when designing APIs. We tend to
design APIs only for ourselves instead of thinking clearly about the customer
scenarios.