I worked on a team that provides high-volume data services. I designed an interface change to expand our partner network and serve more customers. The interface embeds the desired data services in the record. Originally, the various requests being made were encoded in a bitmap attribute, stackable, compact, and efficient. When we published the interface for new partners, we wanted something human-readable and more usable for business users. I designed a series of character-based service requests that the partner could read and understand. They could embed the request in a workflow configuration that would be self-documenting.

My design was based on an understanding of the interface. I knew about the bitmap field and what it mapped to. I knew the team that supported the interface. It had been years since the interface had changed. It was very stable. I had documentation on every field in the format, and I believed I could add a request mode without changing how it worked at its core.

I had every reason to be confident the plan would work.

The processing code enforced a rule that only one record per account could be handled in a single file, whether that record requested one or many services. The new design allowed for request stacking with multiple records in a file. When a new customer sent a file requesting multiple services for their accounts using multiple records, the file was quarantined with a fatal error and all their files were frozen. The customer had to reconfigure their requests to stack them in a single record. We needed to specify and map a series of new multiple-request service request strings for them to send us. This fix created a delay of several days; meanwhile, their initial workflows were broken.

This is a work design problem.

What the documentation covered

The documentation described each type of record, each attribute, and each of the services and how to stack them in a single request. What it didn’t say was that it required all of the service requests for an account in the file to be stacked in a single request record.

That rule lived only in the code.

What this failure uncovered

Two conditions were assumed to be true: 1) the publisher of the interface would always own both sides of the interface and 2) the developer who expanded the interface would be the one who originally owned it. These were good assumptions for the world in which the interface was built. The documentation was sufficient for years. That portion of the code never changed and the assumptions remained unwritten. The documentation looked complete.

The difference between the world the documentation described and reality is work erosion.

We created a series of service request strings so the customers could stack their requests in a single record. The long lists of service combinations were harder to select from and a clear pointer to why the bitmap was the original design. When new partners request services, they must ensure that the way they plan to use the services is covered by the list of recognizable requests and stacked requests. On our end, we must map each combination to the services each represents.

Contributors can do their homework and still not be prepared

Reading documentation that exists about a feature or a process feels like it’s enough. What you don’t see can be even more important: the assumptions about the world it operates in. You will discover the truth from the code when it costs you.

Leaders can mistake untested for stable

The most stable part of your system may be one that has never been tested.

The longer you go without changes and the more the world has changed since it was written, the more likely there are hidden assumptions. When you need to make a change, and the change is designed without the ground-level understanding, the costs will feel like the assigned person’s re-work, rather than a cost of old assumptions.

Protect your work for future expansion

Before you change something that hasn’t changed in years, ask the owner what the design assumes about the world in which it operates, who we work with, and who does the work.

When you write about how something works, write the conditions it assumes.

Designers create for the world their system runs in, consciously or not. The Momentum Architecture is a methodology for keeping a description of that world with the work, so the next designer knows what the system relies on before making a change.

This kind of documentation lets the next designer expand your features based on what they know, rather than what they assume. My partner lost several days of operations to that difference.

👉 The diagnostic takes about 10 minutes and shows you where your record is breaking: https://amykennedyleadership.com/choose-your-diagnostic/