API usability is not just about the API itself

Matt Jadud sent some interesting
references to the PPIG (Psychology of Programming Interest Group, www.ppig.org)
mailing list this morning one of which is a fascinating paper from 1963:

CORC -- The Cornell computing language

https://doi.acm.org/10.1145/366604.366651

What is especially interesting about this paper is the lengths the authors went to
in order to improve the whole end to end user experience of using CORC. While the
authors did a lot of work on the design of the actual programming language, they also
did a lot of work on improving compiler diagnostics and run time error messages in
order to reduce the edit-compile-debug cycle (which makes good sense in the days of
punch cards...). This is something that is often overlooked nowadays. For example,
good API design can be let down by poor run time exception messages. I've seen
APIs for example that throw exceptions from base classes when the user has used a
derived class incorrectly, in which the messages refer to the state and context of
the base class even though the user has no knowledge of this class.

It's important to try to provide enough information to let the user know that a problem
occurred and how they might be able to fix it. Obviously this isn't always
possible, but if you can provide any guidance to the user about how to recover from
an error, it's imperative that you do so. Remember that not all of your users will
read the documentation that you ship with your API!