Mary Rose Cook's notebook

The public parts of my notebook.

My homepage.

One-pagers, a technique to handle overwhelming complexity

There are some situations where complexity becomes unmanageable. For example, fixing a bug that involves many interacting pieces of code. Or understanding a concept like git merge that has many cases and a complex underlying set of rules.

In these cases, you're trying to understand a system. A common behavior is to move around the facts and concepts and relations, making sense of a part at a time, but never being able to keep the entire system aloft in the mind. This behavior is a sign of short term memory overload.

If you have five slots for information in your short term memory, and your understanding of the topic is low, you'll fill those slots with only a few of the lower level facts in the system. Therefore, you can't hope to keep the whole system aloft in your mind.

The solution is to increase the amount of information you can hold in each memory slot. You can do this by increasing the size of the pieces of information you put in each slot by grouping lower level concepts into higher level concepts. This is called chunking.

For example. Let's say I'm debugging unfamiliar code. I read the code for some module. The module performs a series of operations. Each time I try to integrate my understanding of something with that module, I need a memory slot for each thing the module does. Thus, my short term memory is easily overloaded.

What I need to do is take the multiple operations of the module and chunk them into one operation in my mind. It might take me a while to figure out, but I can probably summarize what the module does as a single concept that encompasses all the operations. Now, to integrate my understanding of that module with other parts of the program, I only need one memory slot for the module.

Earlier, I described a behavior of moving around the facts and concepts and relations. This will eventually lead to building up these chunks, allowing you to master the complex system. But it's inefficient and frustrating and demoralizing.

A better approach is to create a one-pager. This is a single document that describes the entire system. You create this document by a process of accretion and elaboration. As you move around the system, you keep on adding useful new information about how it works. And you keep on making the information more densely interconnected and and deeper and richer with meaning.

Initially, the document is a flat, unordered list of bullet points and it is not that useful. To make it useful, you repeatedly revise it in two ways. First, you try to shorten it. Second, you try to structure it into nested chunks.

For example, you might successfully chunk several lower level concepts into one higher level concept, as I did when I summarized the code module's operations. If you feel at ease with that higher level concept, you can delete the sub-concepts,. This makes the document shorter and also creates a new, higher level chunk.

As another example, you might have several facts about a particular code module scattered throughout the document. Once you notice a connection between them, you might bring them together and put them under a descriptive heading. This isn't a fully integrated chunk. But grouping related concepts together helps you find them more quickly, study them together, reminds you of they are related, and is a stepping stone to turning them into a single chunk.

The goal here is to create a very rich, densely connected body of information that it's possible to consume in as short a time as possible. Once it's short and rich enough, you'll be able to hold the whole system aloft in your mind.

The idea of the one-pager is pretty similar to the advice, "To understand something, explain it to someone else". But one-pagers are a bit better for two reasons. First, using a document gives you a sculpting table on which to work your knowledge into shape. You can add information, rearrange and refine. Second, the document is a record that lets you reload information into your brain that you've already figured out without having to re-derive it.

So, next time you're drowning in complexity, moving around a system and only able to see the logic of individual pieces and not the whole, try sculpting a one-pager to master the system.