Ergonomics and cognitive load
Contents
The main point of an API is to be used. So how it feels in use is part of its design: end users never see it, but for developers it makes or breaks an API, and a project’s popularity with it. This post discusses two of its qualities explicitly: ergonomics and cognitive load.

This is the fifth post in a series on API design. Generalization as discipline listed the criteria a good API answers to, and a good developer experience and low cognitive load were among them. The posts so far asked what an API should contain: its complete shape, and where that shape comes from, in math, in CRUD (create, read, update, delete), and in functional structures. This post opens the second half, about how to expose it. Each technique in the rest of this series argues from ease of use, and this post states that reason once.
Use is the point
An API is an interface, and its users are programmers, so we are talking about user experience: ergonomics, familiarity, and managing cognitive load.
Ergonomics in an API is its developer experience: how easy the API is to use. It should be easy to memorize and to remember, and easy to combine with other APIs, and its users should feel in charge of it. It should also fit its language and feel natural there: its conventions, its constructs, and so on. The next section takes the first three qualities, and the section on familiarity takes the fit.
Cognitive load is what users have to keep in mind to use an API. Open source, honestly looked at it from both sides: for a maintainer, more interacting parts to keep track of; for a user, a bigger API and more docs to remember.
Cognitive load adds up. It works like the context window of an AI agent: a user keeps in mind the APIs of every dependency, the details of the domain, and the peculiarities of the product. Every new dependency adds to the load in proportion to what it brings: new APIs, arguments, semantics, exceptions, and so on. That is one more cost of a dependency, beside the ones The cost of dependencies counted. How much can we add safely? We don’t know the limit, but it is better to leave as much space as possible for the product our users build and its domain. When we assume too much and load too much, we hurt our users, and our project as well.
What makes an API ergonomic
The first quality is memorability: an API should be easy to memorize and to remember. It is also a big part of cognitive load, as the section on familiarity below shows. Three things help.
Few core concepts. An API should not have too many of them. My rule of thumb is 7±3 core concepts, a looser version of Miller’s 7±2 for short-term memory. Depending on the project, a concept is a class, an object, or a function. Classes and objects follow the same rule for their core methods, and functions follow it for their arguments. Counting functions alone misses the load: one function whose argument selects among dozens of operations still asks a user to learn every operation, and it has to parse and branch on that argument at run time.
Well-chosen defaults. A user should not be concerned with things they don’t use or don’t care about. They should not have to pass stock values just to make a call work. Defaults apply on their own, and a caller overrides only the values it cares about:
// bad call
fn(USE_DEFAULT_CONTAINER, USE_DEFAULT_PERMS,
USE_DEFAULT_SOMETHING);
// good call
fn(); // all defaults
fn({perms: 0o600}); // one value overridden
That keeps the call site tidy and observable, and it helps memorization. The options pattern below is one way to do it.
Essential and occasional docs. Core concepts and defaults split the docs in two. The essential part covers what a user works with constantly, and it is better to know. The occasional part covers what is used rarely, for example to set something up once, and it is looked up only when needed. That keeps the knowledge a user has to carry manageable.
The second quality is orthogonality: one logical concept per component. A component entangled with other concepts is hard to combine with others, and combining it takes glue code. How APIs combine, and what glue code costs, is the subject of an upcoming post in this series.
The third quality is psychological: a user should feel in charge of an API. So an API should be simple to understand, guarantee what it does, and stay predictable in the face of errors. A user should not have to scramble to learn what just happened, and how it affected durable resources. An API can do complex things, as long as they are simple logically: “write an object to a database in a transaction if nobody updated it since I read it, and throw an exception otherwise” is one sentence, whatever it takes inside.
One trade-off, decided twice
Ergonomics comes with trade-offs, and people judge the result by what they see first. Two stories from my work show one trade-off, ease of setup against the size of what an app ships, decided both ways.
Many years ago I trimmed down a web application whose download was too big. Most of the bundle turned out to be the venerable moment.js, a date library. I checked how the app used it and found one place, which formatted a Date as YYYY-MM-DD. We could do that without a library, so I cut moment.js out completely. I suspect that my predecessor planned to use more of it, and the plan didn’t pan out.
Then I wondered why one trivial format needed so many bytes. It required a locale bundle, and every locale bundle was included, just in case. I think that originally a programmer was supposed to load the needed locales separately, that many didn’t, and that it broke some algorithms. So users dropped the library after the first try as “buggy,” filed “bugs,” or spoke badly of it. My reading is that the authors got tired of it and made the library fool-proof: they included everything, so it was impossible to fail.
That was an old version, and the library could have changed many times since. Its current docs confirm the effect: with a bundler, every locale is included by default, which is “the simplest option” and “produces the largest bundle.” The fool-proof default worked, and every user paid for it in size, including those who needed one date format. Personally, I try to avoid such solutions.
Dojo made the opposite choice. I was a very active contributor and a committer, and it was a massive project. I learned there that a lot of what happens to a project is social.
The JavaScript libraries I saw at the time were “just include this file,” and the most advanced packaging was “run a minifier and concatenate the files.” Dojo had a build system, so an app shipped only the pieces it required. The builder was a modified Rhino, an implementation of JavaScript in Java. Using it meant setting up Java, downloading a relatively large JAR file, and configuring the build.
Dojo included a lot of algorithms and data structures, and a zip file of all of it was in single-digit megabytes. The builder’s JAR alone added at least a megabyte. A developer who looked at that zip concluded that Dojo was huge: who can afford a client-side application in megabytes? There was no Node yet, downloading megabytes was slow, and not every device could run such an app. The concept of a build was foreign to many. So the tool that let an app ship less also made the download people judged bigger.
In hindsight, the biggest issue with Dojo was its packaging: one downloadable archive bundled all its projects, tools included. The right thing to do was likely a package repository like npm, but Node and npm were years away. Without Node, the builder needed another JavaScript engine: hence Rhino, and Java as a dependency.
That was one of the reasons Dojo didn’t become as popular as it deserved. Its code was sound, yet the setup and the first look decided against it.
That was its era: Dojo was a pioneer in shipping a build step. Today a build step is routine: webpack and other bundlers, TypeScript compiled to JavaScript, and JSX and TSX, which no engine runs directly, so they have to be compiled too. Many developers have accepted them. I still don’t like them, but a bundler, a preprocessor, or a compiler is no longer a source of confusion, and browsers, devices, and today’s networks handle megabytes of a web app easily.
Moment shipped everything, so nobody could get it wrong, and every user paid in size. Dojo shipped only what an app needed, and asked for a build step. Good or bad is in the eye of the beholder. Both show how social factors influence design and implementation.
The lesson I took from Dojo: people judged it by a first impression, formed by the common assumptions of the time, and the impression was wrong. They skipped the docs. It is a purely social reaction, and sometimes developers have to take it into account. In a way it is marketing for open source: the code is free and we are unpaid, yet we have to do it, with blogs, conferences, workshops, and videos.
Familiarity
The last quality of an ergonomic API is a fit with its language and with what its users already know. Compare three ways to introduce an API. “My API has seven major items; let me discuss them” asks a user to learn seven new things. “Its API is the same as Map” asks for nothing new. “Its API is similar to Map, with differences in three areas” asks for three. So the goal is to add as little new knowledge as possible: keep the API small, refer to APIs users already know, and keep the differences and exceptions to that knowledge few. The less an API adds to a user’s cognitive load, the more eager they are to use it.
My re2 applies the principle on purpose. Its RE2 object is a practical drop-in replacement for RegExp, so a user can start by swapping one for the other, and an RE2 can be built from an existing RegExp. Every difference is documented in the README, and the main ones can be checked at run time. RE2 always works in Unicode mode, and a setting, off by default, warns about a regular expression written without it. An unsupported feature, such as a backreference, throws SyntaxError, so the code can keep the RegExp:
import RE2 from 're2';
let re = /(a)+(b)*/;
try {
re = new RE2(re); // a drop-in replacement
} catch {
// an unsupported feature: keep the RegExp
}
re.exec(sample);
Generalization as discipline tells why its API follows RegExp as closely as it does.
Some APIs are defined by tradition. A stack has push() and pop(), both O(1), and secondary operations like clear(), isEmpty, and top. When I write a stack, I don’t need to invent its API, and Math-grounded APIs showed that the traditional set is also the complete one. A user who knows a stack from anywhere else can use mine without reading its docs.
Math is familiar the same way: we know +, 0, and their laws before we open anyone’s docs. So are names shared across a language. In Genericity for free, iterators took Array’s method names, so a programmer who knows map() on an array knows it on an iterator. That post objected to a second hand-written copy of the methods, yet sharing their names was the right call.
The strongest case of familiarity I saw ended the Dojo story. What finished Dojo was jQuery. On the technical level jQuery was nothing special, and Dojo had much more interesting pieces. But jQuery had one thing that won developers over: its API, based on CSS selectors. Call one function with a CSS selector and get DOM nodes back. Suddenly getting a node was easy, and so was getting a collection of nodes. Not everything works well with CSS selectors, but web developers already knew CSS, and now they could use that knowledge in JavaScript.
jQuery was not very efficient technically: browsers gave scripts no way then to find nodes by a CSS selector, so jQuery parsed each selector itself and walked the DOM tree, collecting the matches. Yet the developer experience was good for anyone who could live with that cost, and many did not worry about it. It was a good trade-off, and the main use of $() asked for nothing new: pass it a CSS selector. Even a novice programmer could memorize it and use it, and for a senior one it meant minimal cognitive load.
The effect was social. An instantly familiar and simple API decided it, and jQuery led the JavaScript toolkits for years. Browsers then shipped their own replacement for $(), querySelector() and querySelectorAll(), and new projects needed jQuery less and less. Libraries like Zepto kept a jQuery-compatible API on top of those functions. If I remember correctly, Zepto was smaller and faster, so it could replace jQuery with minimal effort, a simple path to upgrade old jQuery applications in production.
Consistent names and shapes
One sure way to reduce cognitive load is to use familiar analogies, as in the previous section. The other is to be consistent in an API’s structure, shapes, and naming.
Imagine the opposite: an API of ten functions with random names. Some names are nonsense, some don’t say what a function does, and some say something else. The arguments come in random order, and the names of options are picked the same way. Here are three of the calls, next to what a consistent API makes of them:
// bad calls
cats(5, salt); // park 5 trucks in garage salt
mix(salt, 3, pepper); // move 3 trucks from pepper to salt
removeAll(salt); // count trucks in salt, remove none
// good calls
park(garage, 5);
move(from, to, 3);
count(garage);
Such an API is hard to remember and hard to reason about: “so five cats, which are actually trucks, go to a salt, which is actually a garage…”
A real API can do it with only two names. One library I used had a source and a target, yet some of its functions took fn1(target, source, ...) and others fn2(source, target, ...). Mixing them up was a constant cause of bugs in our code. C has the same split: memcpy(dest, src, n) and BSD’s bcopy(src, dest, n) copy memory with the source and the destination swapped, a trap for anyone who uses both.
We tame this complexity by choosing every name with care, cutting what we don’t need, using one predictable schema for arguments, reusing concepts, and so on.
Koleman Nix wrote about naming in How to name things. Five of his points apply directly to APIs:
- Symmetry. Related concepts get names that mirror each other, like
srcanddst, so each name points at its pair. - Names as a set. Names that live together, such as the date columns of one table, are chosen together, so that read as a set they tell one story.
- Essence over need. A function is named for what it does. Why a caller needed it belongs at the call site, in the caller’s own names. His example is
mergeTargetValuesIntoSourceTemplate(), which turned out to be a hand-rolled map union, hidden under a name that describes its first caller. - Shapes. The same thinking applies to a value’s shape. An optional map (
Option[Map[String, String]]) expresses a missing value twice, once for the whole map and once for each key. When an absent map and an empty map mean the same thing, the absent one becomes empty at the boundary. - A design signal. A design that is nearly finished but still resists a name is a sign that something might be wrong. A good name that appears on its own during the work is a good sign.
Nix also warns against “a craving for consistency, as though consistency were a virtue in itself.” The consistency I look for follows meaning: things that do the same job look the same, and a domain’s own language comes first.
- Similar methods get similar names. We
add()a person to a team andadd()an item to a list. - A language’s conventions win too. Languages name things differently: camelCase (
firstName) in JavaScript and TypeScript, snake_case (first_name) for Python’s functions and variables, and so on. It is wise to follow them. A network API is a separate case: I usually shape it by its major consumer, for example camelCase when that consumer is JavaScript in a browser or in Node. - A domain’s language wins. It would be weird to call a stack’s
push()add(). We can addadd()to a stack, but usually for generic programming, which adds items to a list, a heap, or a stack alike. It is an alias for generic code, andpush()stays the name for people. I have a library for aliasing,meta-toolkit, withaddAlias()andaddAliases(). - Similar arguments get similar names and shapes.
To configure an object, I usually pass its constructor an argument called options, a dictionary that holds properties. When it is flat, with no sub-dictionaries, I use the same pattern for defaults and class-level overrides, so users always know how it works and what to expect:
const defaults = {crlf: system.isWindows, cached: true};
class X {
static overrides = {cached: false};
constructor(options) {
const opt = Object.assign(
{}, defaults, options, X.overrides);
// ...
}
}
Each source overrides the ones before it. cached defaults to true, a user’s options can turn it off, and X, which has no cache, turns it off whatever the user passed and says so in its docs. meta-toolkit has a helper for the same merge, which keeps options clean: copyOptions() copies only the keys that defaults declares, so every option, an override included, needs a default. A default of undefined declares a key without setting it.
import {copyOptions} from 'meta-toolkit/options.js';
const opt = copyOptions({}, defaults, options, X.overrides);
Being consistent in things like that helps manage cognitive load. Nobody asks “how are my options handled?”, “is an option a number?”, or “can I supply options?”
It also helps meta-programming and generic programming. If I know a shape, I don’t need to know how exactly to work with each object: I can create any object by its constructor, or add an item to any container. That is Stepanov again, from Math-grounded APIs, and the idea of Genericity for free: an operation written once works for every type that shares the shape.
Checks, adapters, and the complaints we hear
The complaints in the moment.js story raise a related question: how much validation of data and arguments does a function need? Some go overboard. By my estimate, a simple function can have 80% or more of its code dedicated to checks and adapters, which obscure its useful part. The function becomes a place for checks, and its main algorithm a distant second.
Why do people do it? Usually to avoid being bombarded with bug reports about misuse. “I use your sin() with an array, and it didn’t work”: let’s support arrays and calculate the sine of every item. “I used it with '3', and it didn’t work”: let’s convert it to a number. “I used it with 'three'…”: we may add a locale-specific conversion of written numbers. After a few rounds of that, the function looks like this:
const sin = x => {
if (Array.isArray(x)) return x.map(sin);
if (typeof x === 'string') {
x = parseNumber(x); // '3', 'three', ...
}
if (typeof x !== 'number' || isNaN(x)) {
throw new TypeError(`sin() expects a number: ${x}`);
}
return Math.sin(x);
};
The useful part is the last line. A reader can hardly get its idea from the source beyond “let’s check everything.”
How to avoid it? Docs. Well, in my experience few people read docs. A README gets a glance at its setup section and maybe one to three simple examples. Users expect an API to be familiar and to conform to their expectations, and they open the docs only when something goes wrong. That is why inline docs are important: they reach users where they write code. JSDoc comments show up in an editor on hover and in completions through the Language Server Protocol (LSP), and an AI assistant suggests calls as a user types. The other way is to check everything, adapt everything, and print detailed error messages that tell users what to do.
I do rely on docs, but my main line of defense is a simple and familiar API. The simpler it is, the better, and if it leverages prior knowledge, better still. On checks and adapters, I prefer to follow statistics. When something causes regular mistakes, we should change it, so my first option is an API that eliminates that type of mistake, if possible. Math-grounded APIs showed two: readFile() opens, reads, and closes a file in one call, so there is no close() to forget, and a helper can do the four steps of fetch() at once, the ok check included. Otherwise, I add checks, aimed at what feedback and my experience show to be a source of problems.
The problem is that statistics are hard to get without telemetry. By my estimate, when a mistake is avoidable and the workaround is simple, one complains for every hundred people who tried, failed, read the docs, and fixed their code. A bug that is hard to avoid, hard to work around, or unclear draws complaints in droves. Some users, usually new ones, complain about neither: they switch to another project or drop the technique. Even a small bug leaves an unpleasant impression. So bug reports are far from real statistics, because we hear only from those who complain. If my reading of the moment.js story is right, that is the sample its authors heard from.
The rest of this series
The rest of this series takes up techniques for exposing an API: fluent interfaces and immutable objects, operations that state their intent, implementation techniques, and how APIs fit together. Each argues from the same reason: an API is there to be used, and the less it asks its users to keep in mind, the easier it is to use.
Summary
- An API exists to be used, so its ergonomics and the cognitive load it puts on users are design criteria. The load adds up across dependencies, so an API should leave room for the product its users build.
- An ergonomic API is memorable (few core concepts, well-chosen defaults, essential docs apart from occasional ones), orthogonal, predictable enough that its users feel in charge, and fits its language.
- People judge an API’s trade-offs socially, at first look, by the assumptions of the time: a fool-proof default makes every user pay in size, and a build step, unfamiliar then, made a library that shipped less look bigger.
- Familiarity lowers the load: an API adds as little new knowledge as possible when it is small, builds on what users already know (tradition, math, names shared across a language, an existing API), and keeps its differences few, as jQuery’s CSS selectors showed.
- Consistent names and shapes lower it further, and a domain’s own language comes first.
- An API that removes a recurring mistake beats a check for it. Checks belong where mistakes recur, and bug reports alone are a skewed sample.