I recently mentioned how I like to draw it until it works when I’m ramping up on a new system. Clint Byrum says it so much better in his post System Diagrams are Performance Caches for Cognitive Load. First, this bit resonated with me because it’s exactly the situation I currently find myself in:

Having joined just a few months ago, I was overwhelmed about 5 minutes into the meeting. The individual words and concepts all made sense. JSON parsing slow. Network transit treacherous. Changing things at the source hard. I got all of those components of the discussion, but through the whole thing I was just barely able to follow the overall system conversation and ask very basic questions to understand what was going on. I came away with a bunch of exploratory personal action items, and a very clear hole in my mental model of the system that needs to be filled.

Clint goes on to use a systems analogy for the individual people that make up a team—people and knowledge as components of caching, computation, and storage. This leads to a perfect explanation for why system diagrams are so important:

A single system diagram is where those primed nodes can push the most relevant bits of their information out of their local brain-caches, and into a high-performance distributed cache from which everyone can read. This will preserve precious cognitive load for those critical low-latency tasks. Of course, all of these caches may be stale. The local in-memory ones are particularly hard to test, but at least the system diagram is observable. Everyone can look at it, and if there are nodes with updates, they can update the cache.

So, prime those caches. Draw it until it works!