A letter to the owner of the system everyone wants to rewrite.

Dear owner of the old system,

You know the one. It was built years ago, maybe by someone who has since left, maybe by a vendor who no longer answers the phone. It's slow in places. The screens look their age. New hires need a week to learn its quirks, and your developers sigh when they open the code.

Lately, the same sentence keeps coming up in meetings: "We should just rebuild it properly." Someone has a picture of the new version, clean and modern, and it's a good picture.

We're writing because we've been on both sides of this decision, and we'd like you to make it with your eyes open. This isn't a sentimental case for keeping old software. Sometimes the old thing really does need to go. It's a case for being careful about how.

What the old system knows that nobody wrote down

Every long-lived business system is full of decisions. Most of them were made in response to something that went wrong: a customer who was billed twice, an order that shipped to the wrong place, a regulation that changed, a partner who sends files in a strange format.

Somebody fixed each of those, usually quickly, usually in the code, often without updating any document. That odd checkbox on the order screen. The extra step in invoicing that only applies to accounts opened before a certain year. The report that runs at 2 a.m. for a reason nobody remembers. The rule that treats one customer differently.

When a rewrite is scoped, the brief often says "everything it does now, but better." The first half of that sentence is the hard part, because "everything it does now" is largely undocumented. The old system's ugliest corners are usually where the business learned something the hard way.

That knowledge is valuable. A rewrite that loses it will relearn it, one incident at a time, in front of your customers.

Your people know much of it, even if nobody wrote it down. Watch how they actually use the system for a day and you'll hear it: "I always check this first," "we never use that button," "for this customer we do it by hand." Each of those sentences is a requirement.

Why the big rewrite tends to run long

A full rewrite asks the team to rebuild all of that knowledge before any of the new system is useful. Until it can do everything the old one does, your people keep using the old one.

Meanwhile, the business doesn't stop. New requests still arrive, and they land on the old system, because that's the one in use. So the target the rewrite is chasing keeps moving. The team ends up maintaining two systems, and the new one hasn't helped anyone yet.

Then comes the switch, a big weekend where everything moves at once. Years of data move with it, and old data is never as tidy as anyone hopes. There are duplicates, half-filled records, and values that only make sense if you know about a workaround from years ago. It's the moment with the most risk and the least room to back out.

None of this means rewrites always fail. It means the risk is concentrated in a long stretch with no payoff and a single cutover at the end. If you can arrange the work so value and risk arrive in smaller pieces, you usually should.

What we'd suggest instead

Replace it one piece at a time, while it keeps running. Engineers sometimes call this the "strangler fig" approach, after the tree that grows around another until it stands on its own. The idea is plain:

1. Pick one workflow with clear edges and real pain. Quoting, scheduling, a customer portal, a reporting job. Something your people would be glad to see change.
2. Build the new version beside the old system. It reads from and writes to the same data, or to its own with a clear rule about which one is the source of truth.
3. Move real users over. Start with a small group, watch what they miss, and fix it. Those misses are the undocumented rules surfacing, safely.
4. Retire that part of the old system. Turn off the old screen or job. If you need a period where both write the same records, give it an owner and an end date, as in our dual-write checklist.
5. Pick the next piece.

Each step delivers something people use. Each step is small enough to reverse. The data moves gradually too, with each piece taking the records it owns, so problems show up in small batches rather than all at once on launch day. And if priorities change halfway through, you're left with a better system, not half of an unfinished one.

When a rewrite is the right call

We'd be doing you a disservice if we pretended it never is. A clean replacement makes sense when:

• The old system can't be run safely, for example, it depends on software that no longer gets security fixes and can't be isolated.
• Nobody can change or deploy it, so even small pieces can't be routed around it.
• The business has changed so much that the old rules are mostly wrong, and you'd be preserving the wrong things.
• It's small, and a single, well-rehearsed switch is genuinely less risky than a long overlap.

Even then, start by writing down what the old system actually does, by watching the people who use it, not just reading the code.

And even then, keep the old system readable for a while after the switch. Somebody will need to look up how an old order was handled, and "we turned it off" is a poor answer to an auditor or a long-standing customer.

Before you decide

Three things we'd ask you to do first. Spend a day with the people who use the system most and list what they rely on it for, including the workarounds. Find the parts nobody can change today, because those shape everything else. And name the first piece you'd replace if you went the gradual route, and what would change for the people using it.

If, after that, a rewrite still looks right, you'll scope it far better. If it doesn't, you'll have your first piece. This is the kind of decision we work through at the start of web application projects, and we're happy to do it with you. Tell us about the old system, quirks and all.

With respect for what it's carried so far,

TWIMCO, from the studio

Related work: Howcast.