4 A Team’s Shared External Memory
There is a limit to what a team can keep in their heads.
That sounds obvious, but I think we underestimate this limit all the time.
When we talk about complex software systems, we usually think of complexity as a property of the technology. The database is complex. The integrations are complex. The business rules are complex.
But over the years, I realized there is another kind of complexity that is much harder to see.
It is the complexity of understanding.
I first became aware of this on the fashion manufacture project I described in the previous chapter.
When we introduced Event Storming, something changed.
We suddenly had something that represented our current understanding of the business. Instead of trying to explain ideas in isolation, we could point at the model. Six people with six different perspectives could gradually build a shared picture together.
For a while, that felt like the solution. Then another problem appeared. Understanding the system was only half the challenge. The other half was keeping that understanding connected to reality. Because the moment we started building the system, reality didn’t stop changing.
The challenge became particularly visible when we started working on customer master data. At first, it looked like a fairly typical migration project. The company was replacing a home-grown ERP system with SAP. The existing customer master data structure had evolved over many years. SAP organized the same information differently, and our system had to bridge those two worlds.
Naturally, we approached it as a technical problem. We needed to transform data from one structure into another. We had to integrate with SAP. We had to expose APIs and make sure everything communicated reliably.
But the longer we worked on it, the more we realized that moving data was never the difficult part. The difficult part was understanding what the data actually meant.
The old system contained years of accumulated business decisions. SAP introduced its own concepts and constraints. Between those two worlds lived contracts, customer relationships and business rules that were not fully visible in any single place.
Our system had to reconstruct customer master data from information that was now fragmented across different parts of SAP. SAP simply couldn’t represent the information exactly as the company’s services expected it, so our software had to translate between the two worlds.
And that translation turned out to be very tricky. I don’t remember a single moment when we suddenly realized that this had become too much. It happened gradually. Another mapping rule. Another contract exception. Another customer with special handling because of a business decision made years ago.
Piece by piece, the picture became more detailed until nobody could comfortably hold it all in their head anymore. The interesting thing was that the knowledge itself wasn’t missing.
The domain experts understood how customer data was actually used throughout the company. The business analysts knew the processes and had documented many of our decisions. We developers understood the implementation details and the technical constraints.
Everybody held an important part of the puzzle. The problem was that nobody could see the entire picture alone.
Looking back, I think this is an important characteristic of every sufficiently complex software system. The knowledge isn’t stored in one place. It is distributed. Some of it lives in documentation. Some of it lives in the source code. Some of it lives in the database. And some of it only exists in the experience of the people who have worked with the system for years. Each of those representations is valuable.
The business analysts documented processes and decisions that would otherwise have been forgotten. The source code captured the rules we had implemented. The database reflected years of business activity. Every representation contained knowledge.
But each representation only made sense to part of the team. Developers could understand the code. Business experts could explain the processes. The database faithfully stored the history of the business, but it certainly didn’t explain itself.
Whenever we encountered something unexpected, we had to connect those different perspectives again. Someone noticed an unusual customer relationship. We inspected the data. We followed the implementation. We talked to the business analysts. We asked the domain experts. Only then did the whole picture slowly emerge.
Looking back, this was probably the first time I realized that building the software wasn’t the only difficult problem. Making the software understandable was just as important.
At some point, I started feeling that we needed another way of looking at the system. Not another document. We already had those. Not another technical log that only developers would ever read. We already had plenty of those as well. What we were missing was a way to observe the system from the perspective of the business.
I still remember that suggesting this felt like a bit of a gamble.
I was working as an external consultant. My colleague and I weren’t employees of the company. The business analysts and domain experts we collaborated with every day were the people who owned the business knowledge and ultimately decided where the budget should be invested.
Nobody had asked for a monitoring application.
There wasn’t a requirement that said:
We need a better way to understand our customer master data processing.
It was simply something I had observed while working with the team. Every time something unexpected happened, we had to reconstruct the same picture again. We looked at the data coming from SAP. We examined the mapping logic in our own system. We revisited the business rules around contracts. We checked our assumptions against what the domain experts expected. And I kept thinking: what if we could simply make this visible?
At the time, I certainly wasn’t thinking about shared memory. I just thought it would be useful if we didn’t have to reconstruct the same understanding over and over again.
So I proposed building a monitoring application. Honestly, I wasn’t sure how people would react. Usually, external developers are hired to solve problems that the organization has already identified.
This time, I was suggesting that there was a problem nobody had explicitly described yet. Fortunately, the team trusted me enough to give it a try. The purpose of the monitoring application was simply to show what was happening. SAP continuously sent incremental updates. Our system received those updates and reconstructed the customer master data structure expected by the company’s services. Most of the time, everything worked exactly as intended. Sometimes it didn’t. A customer relationship couldn’t be reconstructed. Some required information was missing. A combination of values appeared that nobody had anticipated. From a purely technical perspective, many of those situations could simply have been treated as errors. The system could have thrown an exception and stopped. But that wasn’t really the problem we were trying to solve. The problem wasn’t always that the software was broken. Quite often, the software was telling us that our understanding of the business was incomplete. That distinction turned out to be incredibly important.
If we reduced every unexpected situation to a technical failure, we lost the context that would help us understand what had actually happened. Instead, we recorded those situations. We kept the incoming information, the decisions our system had made and the exact point where our existing assumptions no longer matched reality. The monitoring application made those situations visible. It didn’t try to hide the complexity behind a polished user interface. Quite the opposite. It exposed exactly the information we needed to understand the system’s behavior.
What surprised me wasn’t that the monitoring application helped us developers. Of course it did. Whenever something unexpected happened, we suddenly had a much better starting point for our investigations. The real surprise came from somewhere else. The business analysts started using it. Nobody asked them to. Nobody trained them extensively. They simply added it to their daily routine. Every morning, they checked whether there were new situations that required attention.
I still remember watching this transition happen. In the beginning, we explored the information together. We explained what different situations meant and how the technical details related to the business processes. But it didn’t take long before they no longer needed us. They learned how to read the information themselves. They understood which situations represented expected behavior and which ones indicated a genuine problem. Most importantly, they could now communicate directly with the SAP team without us developers acting as translators.
That changed the dynamic of the entire project.
Previously, the business analysts would notice something unusual and ask us what had happened. We investigated the code, inspected the data and translated our findings back into business language.
Now everybody started from the same place. Instead of asking,
Something strange happened. Can you developers figure out why?
the conversation became,
We can see this update from SAP. This customer relationship couldn’t be reconstructed because this information doesn’t match our current assumptions.
The understanding was no longer hidden inside the people who had built the software. It became something the whole team could work with. At the time, I didn’t have a name for what we had created. I only knew that it felt fundamentally different from the documentation I had worked with before.
Documentation described the system. The monitoring application participated in understanding it. It stayed connected to reality because reality itself continuously updated it.
Looking back, I think this was the first time I encountered something that acted like a team’s shared external memory.
Not a replacement for conversations. A place where conversations could begin from the same shared reality.