glossary
complexity
The sum of every explanation. Weighted heavily towards future explanations. Measured in bits, but only relative to your audience's expectations.
See also:
coupling
The degree to which two things tend to be explained together. Sometimes it helps, and sometimes it doesn't.
See also:
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:
explanatory power
The degree to which one text, explained first, makes another text less surprising.
See also:
locus
The vertex in a structure which is naturally explained first. Often, it's also where our explanation ends. For instance, when looking at a class, function, or value, we begin with the name. And sometimes, that name tells us all we need to know.
See also:
prefix
The things that your audience already knows. Provides explanatory power for the content of your explanation.
See also:
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:
suffix
Everything you anticipate explaining in the future. What your current explanation is seeking to simplify.
See also:
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:
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