August 6, 2024

a brief introduction

As software designers, our goal is to reduce complexity. We want our software to be easier to understand, and easier to change.

These are not distinct concerns. For our software to be understood or changed, it must be explained; we must tell a story about what our software is, and what it's expected to become. When understanding software, we tell that story to ourselves. When changing software, we tell that story to others. Software which is complex takes a long time to explain.

Our explanations are scoped to the task at hand. When we onboard someone, we provide a broad and shallow overview. When we perform a code review, we narrowly focus on the salient details. Good design makes all of these explanations simpler. The complexity of a system is the sum of its explanations.

An explanation is a message. According to communication theory, it can be measured in bits. But the information conveyed by a message, its surprisal, depends on its audience. For something to be surprising, it must be unexpected.

And so, simplicity is not intrinsic; it does not arise from our code's size or syntax. Simplicity is a fitness between software and our expectations.

There are two core tasks in software development: design and implementation. As designers, we set expectations. As implementers, we try to realize those expectations. In both cases, we are pursuing simplicity.

Design often occurs around our code, rather than within it. A README is software design. Onboarding is software design. Code review is software design. Answering a question is software design.

In literary theory, these external documents and discussions are called paratexts. These paratexts "surround, shape, support, and provide context for texts. They may alter the meaning of texts, further enhance meaning, or provide challenges to sedimented meanings."¹

And so, in the posts that follow, we will explore both text and paratext. We will analyze the combined meaning of our words, our diagrams, and our code. We will attempt to understand how we understand software.

---

This post is an excerpt from my (incomplete) book on software design. For more about the book, see the overview.