It’s easy to look at a software tweak or feature and think, “Oh, that shouldn’t be too hard, right?” Some things sound smaller than others, and even the big ones don’t sound THAT big. It’s a trap even engineers and product people fall prey to.
But one of the top two rules of software development is no change is a small change. Altering a code base isn’t like projects in other spheres of industry. You hire an employee, train them, and off they go. You take inventory, reconcile, and then re-order. But a code base? A code base persists in all its complicated glory, and any single change can affect any number of previous changes.
We recently ran into a classic case of this, with what at face value appeared to be a simple change. It’s a great example of how:
- We can do a basic estimation of dev work, but without getting into the weeds it’s a guess at best.
- It’s impossible to predict exact release dates of larger features.
The Problem
When editing a Document Type in Smart Cabinet, you can move that “Start Date” into the past, but you couldn’t move it up in time.
If you’d like to know what a Document Type is and why you’d want to change the “Start Date”, keep reading. Otherwise, jump to “Our Initial Estimate”…
Why is this a problem?
Well, let’s say I’m trying to keep a clean record of my monthly Visitor Logs across my locations. In that case, I would create a “Visitor Log” Document Type in one of my Binders. I set the “Start Date” to June 2016 to dictate how far back I’d like to retain this document type (in theory, June 2016 would be when a location began operating).
Once I do that, Applied Periods are generated from June 2016 on. So if something changed, and and now we only needed to retain Visitor Logs from February 2017 and beyond, I couldn’t move up the “Start Date” of my Document Type. Long story short, it’s how the system was built initially.
Our Initial Estimate
We knew initially that this was more complicated than just changing a date. Because the “Start Date” is central to how Applied Periods appear in Smart Cabinet, we knew there were a couple of threads to untangle.
But in all, we thought it would take a day or two of work (8-16 hours). Spoiler alert: It took a single developer over three weeks to finish).
The Actual Work
In all, we had to build logic to handle seven different scenarios (when at first it seemed like 1-2). Those scenarios affected Smart Cabinet and Oversight Portal, and beyond that, this change had the potential to affect both companies within an Oversight Portal.
Why seven scenarios? That’s because what the app needed to do varied, depending on four factors, specifically:
- Today’s date
- Current start date
- New start date
- Who was changing the start date (it could been an MJB, but it could also be an Overseer)
Those four factors have A LOT of permutations (see the above diagram). And we discovered those scenarios one or two at a time, with each scenario resulting in more dev work.
What’s more is… of those seven scenarios, some are less common than others from a business case standpoint. Would I want my Document Type to have a start date that is in the future? Doesn’t seem likely, but an unlikely scenario bypassed today becomes a bug tomorrow.
So How Do We adjust?
Beyond reconciling with the fact it’s not always possible to know all the hurdles before starting on even a “small” tweak, over time, we’ve tried to incorporate safeguards to uncover these things earlier. A few of them:
- Trying to anticipate “Affected Areas”. An affected area is what we call a part of the app affected by a change, but that you wouldn’t immediately think of when talking about a tweak on the surface level. For changing the start date, the Oversight Portal would be an affected area.
- Walking the team through upcoming tweaks. As product owners, it’s our job to know what the app needs to do. As engineers, it’s their job to build and to be the experts on the code base. We try to bridge the gap with “face-to-face” conversations (usually at night). This allows them to ask real-time questions, some of which we have answers to, some we don’t.
So there you have it. Just another challenge of working on a software project with over 100,000 lines of code.
Nice article, Dave. That’s a great example and it’s really easy to over-simplify the changes we need to make to the system, which warps our own expectations. This is a great reminder that there’s usually a LOT more to it!
I remember seeing that chart that Gayan sent over and saying “whoooaaaaa”! Even knowing how complicated software can be, it’s easy to fall into the trap of thinking things can be easier than they are!