"It's just a small change" I told myself when I decided to improve my bot handling.

It wasn't.

Now, I want to prefix this with a small disclaimer:

There are cases where a change really is small. Most aren't.

On the surface my thought of "I just want to improve my bot handling and improve SEO" seem simple. I just need to add some meta tags, and start black-listing the most frequent malicious probing request endpoints in my web server, then I just need to add meta tags to my content.

I'm not going to retell the story here, but here I will look deeper into why this small change turned out to be a big change.

The misconception

One big misconception that most people have is that when doing proper architecture and development paradigms everything is isolated and you just need to change something in one place. That is true, but only through a specific context. The context that this is true in is architectural and source code. It is isolated with one source of truth in one place when reviewing the code and the architecture. But if you look at an architectural diagram you will quickly see that there are many intra-dependencies within an architecture. The different parts are depending on outputs from other parts. And with this the change might be simple and small, but the impact can have far reaching consequences.

Does this mean that it is useless trying to implement changes? Definitely not. It is expected that changes happens. I am a big proponent of Agile, and one of the core concepts is "responding to change". It doesn't only refer to the technical landscape, but also to changes in the software. But when making a request for a change, one core concept that needs to be scrapped is "small change". Even the change of wording on a button on a webpage will have knock-on effects.

Let's use this as an example.

You want to change the text of the button on a contact form. At the moment it says "Submit" and you want it to say "Send". This is a minute change. We’re swapping six letters for four. What could possibly go wrong?

The first thing that comes to mind for me as an engineer is that it will change the size of the button, the button will become smaller. Is the button width set dynamically or static? Would it change the layout of the page - like adding a picture to a word document? All of a sudden there is UI and UX concerns with this small change. And that is based on if the button text is actually coded into the button element!

If the text is not on the actual button element but in a centralized string manager, we have a much bigger problem! Where else are we using this string? Submit is a fairly general word, it can be used in registration, profile update, password reset, contact forms, comment sections, etc. If that is the case would it be better to add another string centrally or should we push back on the change? Is there another string in there already that says "Send"?

There are different button types in a web form, one of these is the "submit" type. This has a special behaviour and we might just automatically assign the text "submit" to all submit type buttons. So now there might be a need to create a special handler for the button functionality.

Other implications that can make itself known far later, hidden string dependencies! Somewhere we had added a dependency on the text "Submit" being used. So we will need to run proper integration testing after the change and prepare for any bugs that might be found due to the change.

All of the things I listed are things that hopefully go through the head of an engineer - and this was just for changing the text of a button. This is also why engineers at times can seem resistant to "small changes". We're really not made out of stubbornness - we just recognise the pattern. We need to make sure that nothing breaks when changes are implemented!

"Small" is a label given by a human. It is usually based on the view of the end result, not the system impact.

Software systems don’t understand intent. They are made up of dependencies.

Bad design

Is this by bad design? Sometimes it is, but those are exceptions and not the rule. Of course in some cases it can be bad design. In other cases it is due to technical debt where a decision was made where speed was favoured over correctness (usually due to a "quick small change").

In other cases it can even be a feature for the design choice. In some paradigms reusability is highly valued (e.g. object-oriented design), in other self-containment and readability is more important (e.g. domain driven design). This is of course not an extensive list of design patterns and paradigms, these are just two.

It might be that the system grew organically and it is now a beast of different patched up systems that stay together through hope, prayers, and Elmer's glue. In systems like that, nothing is ever small or easy, because they are extremely volatile and it results in the most random things might be connected.

So in most cases the engineer or the architect was aware of the penalty for a design choice, but the penalty was considered less of an issue than the benefit the choice provided.

How to deal with changes

This is difficult and highly dependent on your engineering setup. But one thing that I would say are the key points:

Make the request in the right place

Don't go directly to a random engineer or developer. Make sure to go to the person that would own the system development. A project manager, a product owner, a delivery lead, or similar. These are the people that have the overall process and progress at the front of their mind. It will also create a trail for the change. This trail is needed to be able to track actual workload over hidden workload. It also places the change in the correct queue and you will be given a definitive "this will happen" and someone becomes accountable for the implementation.

Accept lead times

Even if it might look like a small change. But in practice it will require impact evaluation and testing. These things take time. It might also require a wider implementation than what it looks like from your point of view. Allow for lead time, and accept the estimation given. These estimations are made by specialists who knows and understand the entirety of the system.

Request an Outcome

Do not request a specification where you say "Change this to X". Include the outcome you want from the change. You would be surprised how much that can change how it is being implemented when specialists get to know both the what and why the change is wanted. In our example of the button instead of saying "Change submit to send on the contact page" submit "Change the submit to send on the contact page - to increase clarity for the end-user". All of a sudden there is a clear use-case and a clear argument why the change is important.

Assume high impact

Assume that your change have a larger impact that you see on the surface. The engineers are not being obtuse because they don't want to work. They are performing a risk and impact analysis for the change, they are interested in your system not breaking. I have never encountered an engineer that wanted to do a bad job, all engineers want to do the best job they can with the constraints they are given. This includes not breaking things.

One last thing

To sign off I leave you with this:

That “small one word change” I made to my bot handling? It wasn’t the change that was big. It was everything connected to it.