The Shape of the System

The Pit of Success

A good design makes the right thing the easy thing and the dangerous thing take visible effort, so a tired person falls into doing it right.

implementing reviewing

There is a door at your office you get wrong every single time. You push, it doesn't move, you feel that small hot flush of stupidity, and then you pull, and it opens. You've done this a hundred times and learned nothing from it, because there's nothing to learn. The handle is a vertical bar that your hand wants to grab and pull, and it's bolted to a door that only opens by being pushed. The handle made your body a promise and then the door broke it. None of that is your failure. It belongs to the handle.

Software is full of handles that lie. A function with a reassuring name that quietly deletes your data. A default that does the rarest and most dangerous thing. A flag whose name tells you less than the flag actually does. And every single time, we go and blame the person who reached for the obvious thing, when the obvious thing was a trap that had been built in the shape of the safe one.

The man who took doors seriously was a designer called Don Norman, and he built most of a famous book around the one you keep getting wrong. A handle is a kind of signpost. It tells your hands what to do before your eyes have even finished reading the little PUSH sticker that someone, defeated, has taped above it. When the signpost points one way and the mechanism works the other way, a perfectly competent person fails over and over and learns nothing, because there's nothing in the failure to learn from. The lesson he drew is more or less this whole piece. When an ordinary person keeps getting something wrong, look at the shape you handed them and not at the character of the person holding it.

So here it is for software, said plainly. People don't rise to the level of your documentation. They fall to the level of your defaults. A tired engineer at the end of a long day isn't going to open the manual. They reach for the obvious call, the argument order that happens to compile, the option that's already filled in on the form. The real question was never whether they read the docs. It was what happens when someone does the most obvious thing without thinking about it, because that is what will happen, at scale, for ever. Documentation is a wish. The default is the law.

And a thing that is easy to misuse will get misused, which isn't pessimism, it's just arithmetic. Run any tool past enough tired people on enough late nights and the rare, possible mistake turns into a certainty with a date attached to it. In early 2015 the Steam client on Linux had a line in it that was meant to tidy up a folder. It deleted everything in a directory, and it never bothered to check whether the directory's name had actually been filled in. So on the machines where that name came out empty, the command quietly turned into delete everything, starting from the top, and people sat and watched their entire home folder, every photo and every document they owned, just dissolve. Nobody there was careless. The shape of the tool had folded an empty variable and erase everything I own into the one same keystroke. The danger was just sitting there in the default with the safety off.

The job of a good design is to make the correct path the path of least resistance, and to put real friction in front of the cliff edge. Not to bolt on more warnings. Look at the two ways the version-control tool Git lets you force a change. One of them silently overwrites the work a colleague pushed while you weren't looking, destroys it with no warning, and hands you nothing back in return. The other one refuses unless the world is still where you last saw it, and it tells you about the conflict instead of swallowing it. Guess which of those got the short, memorable name that everyone reaches for, and which got the long ugly one you have to look up every single time. The dangerous tool got the easy handle. The careful one got the handle nobody can ever remember. The names are signposts, and the easy signpost points straight at the cliff.

The deeper move is to make the wrong order impossible rather than just discouraged. For years cash machines let people take their money and walk off without their card, and not because they were fools. The thing they came for, the cash, arrived before the leftover step, the card, and the moment the goal is met the mind closes the file and walks away. So instead of a sticker reading do not forget your card, the fix was to make the machine give the card back first and only then let go of the money, which puts the forgettable step right on the path to the thing you actually came for. In software the same move is a type that won't compile when the state is illegal, or a builder that won't let you send the request until the required field is filled in, or a handle that stops working the instant the transaction is done. You aren't asking anyone to be vigilant. You're arranging things so that the wrong sequence can't even be expressed in the first place.

There's a name for the goal of all this, and it turned up as an off-the-cuff line from an engineer called Rico Mariani, just over twenty years ago, talking about how easy his platform was to use badly and how hard it was to use well. Success, he said, shouldn't be a summit you climb to through trials and willpower. It should be a pit you fall into. Most systems get built like mountains, and then the documentation apologises for the climb. Once you know the shape of the pit you start seeing its opposite everywhere. A configuration language so eager to be helpful that when a user writes the country code for Norway, which is just two plain letters, it reads them as the word no and hands the program back the answer false. The handle, a bare string, lied about the mechanism underneath it, which had quietly decided what those letters meant before anybody asked it to. So when the ordinary, tired, distracted person gets it wrong, stop asking what's the matter with them. Start asking what shape you put in their hand. Then build the thing so that falling over lands them in the right place.

In the manifesto, this is tenets (III) and (XXII).

Sources

  • [Mariani 2003] Rico Mariani (documented by Brad Abrams, popularised by Jeff Atwood), "The Pit of Success". 2003. https://blog.codinghorror.com/falling-into-the-pit-of-success/. Success should be a pit you fall into, not a summit you climb: make the right thing easy and the wrong thing hard; tenet III.
  • [Norman 1988] Donald A. Norman, "The Design of Everyday Things". Basic Books, 1988/2013. https://www.nngroup.com/books/design-everyday-things-revised/. Affordances, signifiers, and forcing functions (the card-before-cash interlock): make the correct action obvious and the wrong sequence impossible to express; tenets III, XXII.
  • [Steam 2015] Valve, "Moved ~/.local/share/steam. Ran steam. It deleted everything on system owned by user" (steam-for-linux issue #3671). 2015. https://github.com/ValveSoftware/steam-for-linux/issues/3671. An unguarded rm -rf "$STEAMROOT/"* with an empty $STEAMROOT erased every file the user owned: an interface easy to misuse will be misused; tenet III.
  • [YAML 1.1] YAML project, "Boolean Language-Independent Type for YAML Version 1.1". 2005. https://yaml.org/type/bool.html. The 1.1 bool tag matches no/NO, so country: NO parses as boolean false: a default that silently decides meaning; tenet III.
  • [git-scm] Git project, "git-push" (--force vs --force-with-lease). git-scm.com. https://git-scm.com/docs/git-push. --force overwrites the remote unconditionally while the safer --force-with-lease refuses unless the remote ref is still where you last saw it, yet the dangerous one got the shorter name; tenets III, XXII.

One of a series of field notes on building software for the way minds actually work: tired, distractible, ordinary, and now partly machine. They all lead back to the manifesto behind them, The Shape of the System.