We usually do tech specs for non-trivial tasks at work, and one day I met one that caught my eye: An engineer of ours was striving to refactor our scheduling logic (it was kinda copy-pasted across the app) and to create a centralized API for this.
What do you think he put into the "Business problem" section of the document?
Right, TL;DR, "I feel like copy-pasting isn't a good solution so I'm willing to spend at least a day building a universal abstraction and change existing logic everywhere it is used".
If you were a business folk, what would you think reading this?
Probably something like "Why in the world do your feelings cost us hours of development and risk of changing something that's not broken?"
Never get approved.
However, being an engineer and reading it, you might feel the same as the developer writing the spec.
Maybe even you want to speak up for the guy: "It's obvious, we need to do that!"
But to make a business guy convinced by giving you time (money) and accepting risk (money again) for the "good tech design" requires going down the rabbit hole of whys behind the things that seem obvious for one who is in code.
The why
Let's use a good old 5 whys here - our goal is to turn your feelings into money
Why is copy-paste bad?
Because in case of future changes, you'll need to go across these "pasted" places to change things respectively
Why are multiple alike changes bad?
Because it multiplies the work by the number of places to change, as well as the possibility that the developer will drop a bug around there
Why does it matter?
Because the work required will grow every time we add one more scheduling and risk of failure as well
Do you feel the smell of money here?
Yep, if we don't put X hours into fixing it right now we will be ending up spending N+1 hours for every schedule-related task.
Money math
If we don't take the risk of regression when doing refactoring now - we will take more risk each time we need to change the business logic
Moreover, eventual refactoring is unavoidable and each time we postpone it becomes more complex and time-consuming in terms of both replacing work and fixing regressions. That's why it's called "debt"
Refactoring time = time for solution + (time to switch solution * implementation amount (for every copy-pasted place))
Risk not having refactoring = risk of code to fail * times it's postponed
Money loss = Refactoring time (dev hours) + Risk not having refactoring (quality-related churn and dev hours to fix bugs)
As you can see each time we copy-pasting one more time it increases the final price of refactoring and risks if refactoring isn't made. One day the maintenance price will surpass the cost of stopping and refactoring immediately.
Spiral of death.
So every "time postponed" will add an "interest" to your problematic area.
Make it sound like money
Let's get back to our guy, what would he write to make it sound lucid for a suit
"We have business logic related to scheduling <list the features business knows and don't want to get harmed>, and it has a bad tech solution in place.
The scheduling logic was used in the new code N times last month/quarter and it took X hours.
If we spend X hours to refactor this, we will spend Y hours less on future changes, and it will be paid off in Z weeks".
Sounds quite business, right?
Now let them decide how much money they want to burn for the sake of moving fast sacrificing the speed in the future.
Yes, sometimes "let debt live for X weeks more so we can finish that release faster" is more than okay. Business needs to sell, grow, and scale, not suffice your striving for beautiful software technical design.
Cheers.
