APIs and the Principle of Least Surprise
Editorial note: I originally wrote this post for the Monitis blog. You can check out the original here, at their site. While you’re there, have a look at some of the other authors for their blog.
I remember something pretty random about my first job. In my cubicle, I had a large set of metal shelves that held my various and sundry programming texts. And, featured prominently on that shelf, I had an enormous blue binder.
Back then, I spent my days writing drivers and custom Linux kernel modules. I had to because we made use of a real time interface to write very precisely timed machine control code. As you might imagine, a custom Linux kernel in 2005 didn’t exactly come with a high production quality video walking users through the finer points. In fact, it came with only its version of the iconic Linux “man pages” for guidance. These I printed out and put into the aforementioned blue binder.
I cannot begin to tell you how much I studied this blue binder. I pored through it for wisdom and clues, feeling a sense of great satisfaction when I deciphered some cryptic function example. This sort of satisfaction defined a culture, in fact. You wore mastery of a difficult API as a badge of honor. And, on the flip side, failure to master an API represented a failure of yours.
Death of “Manual Culture”
What a difference a decade makes. No longer do we have battleship gray windows applications with dozens of menus and sub-menus, with hundreds of settings and thousands of “advanced settings”. No longer do we consider reading a gigantic blue documentation binder to be a use of time. And, more generally, no longer do we put the onus of navigating a learning curve on the user. Instead, we look to lure users by making things as easy as possible.
Ten years ago, a coarse expression described people’s take on this responsibility. I’ll offer the safe-for-work version: “RTM” or “Read the Manual.” Ten years later, we have seen the death of RTM culture. This applies to APIs and to user experiences in general.
