User experience design for APIs

[manuzhang]

In this post, Keras author Francois Chollet first enumerated three problems in API design.

1. Those who write programs usually don't keep those who are going to use them in mind.
   2."smart" developers tend to assume end users have as much background and context as they do.
2. Developers stick with user-hostile tools to perceive extra difficult and fashion.

Good design rules have a founding principle:

you should care about your users

Here are Chollet's three rules for API design:

1. Deliberately design end-to-end user workflows with concepts user are familiar with and without implementation details.
2. Reduce cognitive load for your users which includes using consistent naming and coding patterns and introducing as few new concepts as possible.

   For instance, if you are designing an API for numerical computation in Python, it should not glaringly clash with the Numpy API, which everyone uses. A user-hostile API would arbitrarily use keepdim where Numpy uses keepdims, would use dim where Numpy uses axis, etc

3. Provide helpful feedback to your users. This is how Keras's error message.

   for y, loss, shape in zip(targets, loss_fns, output_shapes):
       if loss is None:
           continue
       if loss is losses.categorical_crossentropy:
           if y.shape[-1] == 1:
               raise ValueError(
                   'You are passing a target array of shape ' + str(y.shape) +
                   ' while using as loss `categorical_crossentropy`. '
                   '`categorical_crossentropy` expects '
                   'targets to be binary matrices (1s and 0s) '
                   'of shape (samples, classes). '
                   'If your targets are integer classes, '
                   'you can convert them to the expected format via:\n'
                   '```\n'
                   'from keras.utils import to_categorical\n'
                   'y_binary = to_categorical(y_int)\n'
                   '```\n'
                   '\n'
                   'Alternatively, you can use the loss function '
                   '`sparse_categorical_crossentropy` instead, '
                   'which does expect integer targets.')

   I usually find myself too lazy to do this, Now I know I just don't care about my users.

Always remember: software is for humans, not just for machines. Keep the user in mind at all times.