blog single

Technical debt you can see from the outside

Network and service diagram on a dark screen

Published on:

August 15, 2024

TAG:

PLATFORM ENGINEERING

BY:

Edgeless Team

Read Time:

5 MIN READ

post detail

Technical debt is usually described in engineering terms: outdated dependencies, missing tests, duplicated logic. Business leaders hear a request for cleanup with no visible return. The more useful conversation starts with symptoms they already feel, such as slow releases, recurring bugs and a growing list of things the team cannot change without fear.

Debt is a maintenance bill

Every shortcut taken to ship faster creates future work. That work is a loan. The problem starts when the interest payments grow larger than the original saving. A team that spends two days a week working around an old integration is paying interest every week, and the principal never goes down on its own.

Every active system carries some debt. The useful question is which debt is charging interest and how much. A messy internal script that runs once a year costs little. A fragile checkout path that breaks during every sale costs a great deal.

The symptoms a business can see

Releases take longer each quarter, even when the changes are smaller.
The same bug returns because the fix was applied in one place and missed in two others.
One person is the only one who can deploy, restore a backup or change a price.
New features require changes in four systems and a manual step in a spreadsheet.
Testing happens by clicking through the site after deployment rather than before.
The team avoids upgrading a library because nobody knows what will break.
Support requests include the phrase we have to do it manually for now.

Each symptom maps to a type of debt. Long releases point to missing automation. Returning bugs point to duplicated logic and weak tests. The single expert points to knowledge concentration. Manual steps point to missing integration. Upgrades that nobody dares attempt point to version drift and hidden coupling.

Measure the cost of delay

Put a number on the work that debt prevents. If a release takes three weeks and the business wants monthly campaign pages, the gap is not a technical preference. It is lost marketing time. If a manual invoice step takes six hours a week, that is a fixed cost the company pays every year.

Ask the team to log interruptions for two weeks. How often does an unrelated bug pull someone off planned work. How long does a deployment take. How many support tickets end with a manual fix. The log turns a vague complaint into a list of costs that a budget owner can compare with the fix.

Engineers reviewing an incident timeline — Count interruptions and manual steps for two weeks. The pattern is usually clearer than any code metric.

Pay down the interest first

Fix the debt that blocks other work before the debt that is merely unpleasant. A test suite around the checkout path makes safer changes possible everywhere. A deployment pipeline makes smaller releases possible. A documented backup and restore process gives the team confidence. These changes reduce the cost of every future project, which is why they deserve priority over cosmetic cleanup.

Bundle the work with product changes instead of proposing a standalone cleanup quarter. When a feature touches an old area, improve that area as part of the feature. The team gets a business reason to be there, and the improvement ships with evidence that the area works.

Set a rule for the worst cases. If a module causes more than a set number of incidents in a quarter, it enters a planned replacement. A threshold turns an argument about perfection into a decision rule that everyone can apply.

When to stop patching

Some systems reach a point where each fix creates two new problems. The signs are familiar: no one understands the whole flow, the original vendor is gone, and the test coverage is close to zero. At that point, a replacement is usually cheaper than another year of patches, even though the replacement looks larger on a quote.

A structured comparison helps. Estimate the annual cost of patching, including interruptions and manual work. Compare it with the cost of a replacement spread over three years, including migration and training. The smaller number does not always win, but the comparison moves the decision from opinion to evidence.

A simple way to rank the work

Score each item on two axes: how much work it blocks and how often it causes an incident. High on both goes first. High on blocking but low on incidents is next, because it limits the roadmap. Low on both stays on the list and waits. The score does not need decimal places. A three point scale is enough to start a conversation.

Blocks planned work for more than a day: score 3.
Causes an incident or manual fix every month: score 3.
Requires a specialist to touch: add one point.
Has no test coverage on a critical path: add one point.
Is invisible to users and stable: score 1.

What good maintenance looks like

A maintained system has a few visible habits. Dependencies are updated on a schedule rather than in a panic. Backups are restored to a test environment at least once a quarter. Alerts fire when errors rise, not when a customer calls. The team can describe the architecture without opening a diagram from three years ago.

None of those habits is dramatic, and together they keep the interest rate low. Keep the shortcuts small, visible and paid down before they compound.

Making the case to finance

Finance teams respond to recurring cost, not to code quality. Convert the maintenance work into hours and multiply by a loaded hourly rate. Add the revenue at risk from incidents and the campaigns that were delayed. The total is usually large enough to justify a planned fix without a debate about engineering preferences.

Offer options rather than a single proposal. A minimal option that fixes the critical path, a middle option that adds automation, and a larger option that replaces the worst module. Decision makers can choose based on cash flow instead of rejecting the whole request.

Debt becomes a problem when the interest is paid in delays, incidents and manual work. That is the point to schedule the fix.
Edgeless Team

A quarterly review that keeps it visible

Review the debt list every quarter with the people who own the product and the people who maintain it. Rank items by the work they block, not by how bad the code looks. Retire items that no longer matter. Add items that appeared since the last review.

Report the review in business language. Releases per month. Time from request to live. Incidents per quarter. Hours of manual work removed. Those numbers show whether the maintenance effort is paying off, and they make the next request for time easier to approve.

Keep the list short enough to act on. Ten items with owners beats forty items in a spreadsheet. Anything that has sat for three reviews without moving should be removed or replaced, because a list that never changes teaches the team that the review is theater.

We assess codebases for release speed, reliability and maintenance cost, then plan the fixes that unblock the roadmap.

Explore platform engineering

Treat technical debt as a cost that has to be seen and managed. Name the symptoms, measure the interruption, and fix the debt that blocks work first. The rest can wait until it starts to cost something.

Technical Debt

Maintenance

Engineering

Technical debt you can see from the outside

Let's Talk About Your Project