August 23, 2024

glossary

Definitions and references for this newsletter's core concepts.

complexity

The sum of every explanation. Weighted heavily towards future explanations. Measured in bits, but only relative to your audience's expectations.

See also:

• a brief introduction

---

coupling

The degree to which two things tend to be explained together. Sometimes it makes things simpler, and sometimes it doesn't.

See also:

• coupling as co-explanation
• decoupling in depth

---

explanation

The core task of software development. When we try to understand software, we explain to our software. When we change software, we explain it others.

See also:

• a brief introduction
• the anatomy of an explanation

---

explanatory power

The degree to which one text, explained first, makes another text less surprising.

See also:

• the anatomy of an explanation
• transparent like frosted glass

---

locus

plural loci (LOW-sigh)

The vertex in a structure which has explanatory power for all the others. It is where our explanation naturally begins, and often ends. As an example, consider how often the name of something — a class, a function, a value — suffices in an explanation. And even when it doesn't, we still reference it by name.

See also:

• better explanations through coupling
• transparent like frosted glass

---

paratext

An external text that shapes how our text is understood. In software development, the text is our code, and the paratext is everything else: the conversations, the diagrams, the READMEs, and so on.

See also:

• a brief introduction

---

pharmakon

An Ancient Greek word that meant both remedy and poison. Typically used to describe something that is only beneficial when paired with expertise. Most heuristics for software design are pharmakons; they are only applicable in certain situations, but don't explain what those situations are.

See also:

• making things better

---

prefix

The things that your audience already knows. Provides explanatory power for the content of your explanation.

See also:

• the anatomy of an explanation

---

simplicity

A fitness between content and expectation. The opposite of complexity.

See also:

• a brief introduction

---

structure

An undirected graph, where the vertices are concepts and the edges are relationships. Usually, each vertex contains its own substructure. At lower levels, each structure corresponds to a contiguous chunk of code. Since each vertex is shaped and constrained by its neighbors, a structure is an amplifier: by explaining one vertex, we begin to explain the others.

See also:

• better explanations through coupling
• similar, but different

---

suffix

Everything you anticipate explaining in the future. What your current explanation is seeking to simplify.

See also:

• the anatomy of an explanation
• making things better

---

surprisal

Also known as entropy. We prefer this term because it emphasizes that the information content of a message is always relative to the recipient's expectations.

See also:

• a brief introduction

---

tacit knowledge

Something that we know, but struggle to articulate. Usually learned through repetition.

See also:

• the anatomy of an explanation
• The Tacit Dimension by Michael Polanyi

---