I was listening to another pointless politics-adjacent podcast today, and they were discussing this concept that some people would know only through conservative politics lens - originalism. Wikipedia tells us that it’s a legal theory in the United States which bases constitutional, judicial, and statutory interpretation of text on the original understanding at the time of its adoption. Originalism consists of a family of different theories of constitutional interpretation and can refer to original intent or original meaning.
As you’d immediately see this paragraph is also a perfect example of another concept - american exceptionalism. I can assure you, this idiocy about reading the old, outdated text and trying to govern the current modern state is not unique to the US, and it predates US by large margin. But that’s not what I wanted to write about.
In our industry we have this idea and concept of a design document, which is sometimes used to describe the system as it should be implemented, and this is the text which will likely be reviewed and debated upon. It’s a useful concept, even though it gets abused a lot. Unfortunately in most cases design documents don’t include the concept of ongoing maintenance, and, what’s worse, they lack reasoning for choices taken. For example, the design doc could describe the API calls or a data structure chosen to hold some elements, but it would omit the reasons behind that:
As the number of active users of the system is assumed to be below 100000, and the pinned state of a single user doesn’t exceed 10 kilobytes, let’s just hold all state in memory on a single machine, in a map.
Most of the design docs actually don’t have that. They would only contain “the user state is stored in memory, in a map” and that’s it. But if we’re lucky, the software actually gets used and these original assumptions become invalid with time. Now we actually have a problem when we try to maintain the system - do we treat the original design as a gospel and never try changing it? What is going to break if we do? What is going to break if we don’t?
I’ve actually encountered so many bad variations of this. The classic “layers” example would be some sophisticated layer next to the original map, the original map changed to hold pointers or IDs into that second layer, etc. And the change would have its own design doc with one of the main selling point be “we didn’t change the original design!”.
You are supposed to change parts of the original design if they no longer fit for the purpose. But to do that, you need to understand the intent and the assumptions behind each of the design choices. Then you would be able to switch to modern technology, or to simplify the system if something is not needed anymore.
And to understand the intent, you need to have it written down somewhere.
So when you write design documents of any kind, please include reasoning for your choices, and assumptions that reasoning is based upon. Things change.