Blog ·
Explaining technical debt to a non-technical client
The hardest conversation isn't about price: it's asking for two weeks to change something the client will never see. Explained as risk with a number, it stops being a request for faith.
The hardest conversation in independent work isn’t about price. It’s asking for two weeks to change something the client will never see.
Explaining it in engineering terms fails — and it deserves to. “The service has three thousand lines and no tests” is a description of my discomfort, not of their risk. From the other side of the table it sounds like a craftsman asking for permission to sand something that already works.
Translate each item into a risk with a consequence
What changed the conversation was translating each point into a risk with a consequence and a probability, in their language:
- Not “there’s no tenant filter on these queries” but “there’s a path where one company could see another’s numbers, and if it happens once you’ll be explaining it to a customer”.
- Not “this method isn’t transactional” but “if this fails halfway, the delivery is recorded and the stock isn’t, and someone reconciles it by hand”.
- Not “the schema isn’t versioned” but “we can’t rebuild the database from scratch, so a serious failure is a long recovery instead of a short one”.
Then a rough cost, and — this is the part I used to skip — an honest statement of what happens if we don’t do it. Sometimes the answer is “we live with it”, and that’s a legitimate business decision, made by the person whose business it is.
Two things I learned the hard way
Never bundle debt work into a feature estimate to sneak it in. When it slips, you’ve lied about the feature.
Bring the risks as a list to prioritise together, not as an ultimatum. The client knows things about their exposure that I don’t: which of their customers is sensitive, which time of year tolerates no interruptions, which process has a paper fallback.
Technical debt explained as technical debt is a request for trust. Explained as risk with a number, it’s a decision — and business decisions belong to the person who owns the business.
It’s the same principle we work by at YSY Software: the client decides with information, not with faith. That’s why every stage is quoted as a fixed price and every risk is discussed before, not after.