Rich Hickey is the king of saying simple obvious stuff that is not at all obvious to me until he says it. His latest talk, Design in Practice, is a modest buffet of tips and tricks around a common theme: tight language combined with loose preconceptions can unfold hidden dimensions in which a better design may be possible. Best of all, he comes armed with specific techniques and templates you can use to deliberately push farther along the wordcraft / open-mindedness axes to possibly unlock access to these other dimensions.

The talk is pretty good, but there are two tricks in particular which have been so useful for me that I had to share: glossary and decision matrix.

(video at 4:55) Being able to say a lot in a only a few words is a superpower. Being “concise” allows you to make some cuts in pursuit of brevity. Better than that is to be “succinct”, which is brief but still complete. You should name your components with words, if the component changes, the words should change too!

A concrete way to make this advice actually happen in a project is to use a Glossary (video at 8:41). Have one place where the project’s terms can be declared and discussed. The tiny little revolution he introduced for me here is when a term breaks, fix it or abandon it.

In a private codebase I maintain, we had a thing which maintained a basket of software licenses for a single customer. We called this thing a “renewal”, and the basket in question could be a trial, a monthly renewal, or an annual renewal. We introduced a glossary, which gave us a coordinating mechanism to rename this basket to a “flock”, and we nuked “monthly/annual renewal” with “monthly/annual subscription”. Nothing about the CPU instructions of our code changed, just a few human-only names. But all of this code which had long felt vague was suddenly crystal clear, just by deliberately purging the duplicitous “renewal” and replacing it with more precise words. (“Pre-cise” once meant “before cut” by the way, and it is such a luxury in software that even if we didn’t measure twice, we still get a chance to reglue and try a new cut.)

I just started using a glossary in Spotless (#2008) and the upcoming Selfie (#104). I set the glossary as the first pinned issue, and the top comment of the issue is the current glossary. Discussions on the issue have their final result edited into the top comment, and then the discussion is deleted or archived.

(video at 39:10) What is the fastest stroke for swimming on the moon? An experienced swimmer would probably go straight to freestyle. But the real answer is to run across on top of the water - you can do that on the moon!

Whenever we consider a problem, we will always relate it to similar problems we have solved before. Swimming on earth, our power to weight ratio is so low that we inevitably sink to the waterline - the only strokes we can use are strokes where the largest force is just buoyancy, so we put all our power (physical and imaginal) into forward motion with the assumption that ~all of our body is in the water. But if you pay careful attention, you’ll find an ongoing debate about whether it’s best to swim high or low in the water. It’s such a small difference that ~none of us find a chance to make this choice.

This is a real life hidden dimension, only an inch thick, easy to see but easier to overlook. When you go to the moon, this curled-up dimension expands to your full height, but you’ll only get to use it if you notice that it is there.

The decision matrix is a tool for deliberately finding these dimensions - even creating them! Our perception is involuntarily directed by edges, but we can deliberately drag our mental fingers along a surface to find edges that we might have missed. Let’s go through this exercise for the moon swimming.

As you can see, we put the problem we’re trying to solve in A1. Each column is a potential solution (concise name with a succinct description), and each row is a criterion. The goal of the text is not to judge, it is to describe. When I look at <solution> from <criterion>, what do I see? When I look at <breast stroke> from <drag>, I see high drag as we lift to use the arms followed by ideal low drag for the rest of the stroke.

At some point we will have to make a choice, which involves judging what is good and what is bad, but that is subjective. We should keep this out of the text, because we can put it into colors later - it’s easier to agree on what exists than what is good.

The goal of the decision matrix is not to decide1, the goal is to refactor our understanding of the problem to create space for new solutions. It’s not a shopping list, it’s a combination magnifying glass / dynamite stick.

When we add the butterfly stroke to our matrix, we notice there is a section where a lot of the body is out of the water. On the moon, could we maybe get more of the body out of the water?

When we notice this ridge, we have a chance to say “well, what about just porpoising in and out of the water like a dolphin? What if that is possible?” As we examine dolphin jumping, we see how beneficial it is to be out of the water. The butterfly stroke allowed us to notice that the “depth in water” dimension existed, which leads us to a new porpoising stroke which shows us how much space this dimension has, and now we can design a whole new “stroke” which lives entirely within this newfound dimension.

That’s a toy example, but here’s a real example about read/write control in snapshot testing. Also here’s a template you can copy if you want, though it’s such a simple thing I’m not sure you really need one.

Want more like this, hot off the press?