Good explanations
Posted on Jul 17th, 2023

What sets great software engineering teams apart is their deep understanding of the systems they work on. For instance, operating system engineers’ mastery of memory management, process scheduling, and kernel architecture is key for building robust and stable platforms. Similarly, browser engineers’ command of rendering engines, JavaScript execution, and networking stacks are essential to drive web innovations forward. Across fields, the comprehensive perspective empowers high-quality solutions.

Learning the system inside out and maintaining that knowledge takes a lot of work - both individually and as a team. Good explanations are the key to such detailed understanding. Or in other words: good theories of how things work.

What makes a theory good? Rather than simply accumulating facts together, an effective explanation sheds light on the relationship between cause and effect. It also often provides new concepts that help to make sense of the existing information. Let’s look into the following example:

Bad explanation: “Our website is slow to load. The homepage has many images, animations, third-party scripts. The server has an old CPU and little memory. The database has a lot of data. We want to use caching and move to the Cloud in future.”

Good explanation: “Our homepage uses many large media assets that require the browser to make multiple roundtrips and connections. This causes congestion and delays page rendering. Simplifying the page design to reduce the number of requests and employing caching will reduce load times. The server hardware cannot keep up with peak traffic volumes too, so we need to scale up our infrastructure to be able to serve more connections in a given moment of time.”

While the first explanation states more facts about the website, code, and infrastructure, the second interpretation provides clearer reasoning using web performance concepts like “roundtrips”, “assets” and “scaling”. Moreover, it is explicit about the cause and effect. This translates the facts into actionable technical understanding. Let’s look into another example:

Bad explanation: “Our mobile app is draining battery life very quickly. The app makes a lot of network calls to our API. Users have many sessions during the day. We are using GPS to track location in the background. We need to optimise the app to preserve battery.”

Good explanation: “Our app’s high battery usage stems from excessive network activity and continuous location tracking in the background. With each API call and location ping, the radio has to power up which is energy intensive. We can reduce this battery drain by batching API calls rather than making multiple network roundtrips, restricting background location checks to only when critical, and optimising our data payloads to minimise transmission time.”

Once again in this case, the first explanation simply lists factors correlated with battery drain - network calls, user sessions, GPS tracking. But it doesn’t articulate the root causes or actionable solutions. The second explanation provides specific technical reasoning about why those correlated factors are causally linked to battery life. It uses concepts like “radio power up” and “transmission time” to explain the effects clearly. And it suggests tailored optimisations to address the root problems like batching network requests and throttling background location access.

Developing strong explanations takes practice and constant refinement. Here are a few books that provide useful insights on this topic:

  • In a book titled The Beginning of Infinity, David Deutsch argues that creating good explanations and critical thinking, not just data collection, are key drivers of progress.
  • Framing refers to the perspective, context, and conceptual lens through which an idea is presented. In Don’t Think of an Elephant, George Lakoff explains how different frames yield entirely different explanations.
  • In Learning to Build, Bob Moesta provides a great insight into the difference between causation and correlation (The Chapter 4. Causal Structures).
  • By reading Thinking in Systems by Donella Meadows you can learn basic concepts about systems that would help you achieve better understanding of them and thus ability to create good explanations. See some of my takeaways from this book.
Latest publications
Feb 7th, 2024 Talk to someone Nov 4th, 2023 Read the code Jul 17th, 2023 Good explanations Jul 5th, 2022 Solution ownership Apr 18th, 2022 Behind a good process Jan 16th, 2022 Tech debt is a myth Dec 28th, 2021 Note-taking mistakes