Custom software: the specification you write is not the one you need

A custom software project rarely fails on the code. It fails on the gap between what was asked for and what was actually needed, and that gap only appears once somebody has used something.

It is an awkward property of the trade, and both parties spend their time pretending it does not exist. The client writes a complete specification because that is what they were taught seriousness looks like; the supplier prices it as a fixed sum because that is reassuring.

Then the first version arrives, the teams use it, and everybody discovers at the same moment three things nobody could have guessed. At that point the contract meant to protect both parties puts them in opposition.

This article does not propose abolishing the specification. It proposes writing something else in it, pricing it differently, and admitting in advance what nobody can know — which is the only way to avoid blaming each other for it later.

The stable part of a project consists of rules, and they are stated as sentences that are true independently of any interface.

An order number is never reused. An invoice is not edited after issue, it is cancelled. A customer may have several delivery addresses but only one billing address. An item cannot be sold below its purchase price without approval.

Sentences like those are worth more than thirty mockups. They are checkable, they are discussed with the people who do the work rather than with a developer, and they stay true when the screen changes.

The second block to write is the known edge cases, the ones people remember. They will not be exhaustive — that is the previous section’s subject — but each one written down beforehand is a dispute avoided.

The third is what the tool will not do. It is the shortest and the most useful: naming out-of-scope functions explicitly turns a future disappointment into a present decision, and it is the same rule as in construction and events.

One design error recurs throughout line-of-business software: it is drawn on the screen of whoever commissioned it, not on the screen of the person who will use it.

The internet market observatory published by ARPCE counts, for the second quarter of 2025, some 59.10 million internet subscriptions in Algeria, of which 88.71% are mobile and 11.29% fixed.

The ratio does not describe your company, but it describes your teams away from the office: the storekeeper, the driver, the technician on a call, the salesperson on the shop floor. None of them works seated in front of two monitors.

The consequences are concrete and get decided early. A twenty-field form is unusable standing up; an entry needing both hands cannot be done while carrying something; an operation assuming a permanent connection fails in a stockroom or a basement.

The rule we apply is to go and look. An hour spent beside the person who will do the data entry, in their real environment, changes the design more than three meetings — and it happens before the first screen, not after the first refusal.

Moving from the old system to the new is the riskiest moment of the project, and it gets the least attention because it arrives when everybody is tired.

The first decision is the switch: all at once, or in parallel for a period. Parallel is safer and far more expensive, since it means entering everything twice; a clean switch is faster and has no way back after a few hours.

The second is the date. Never go live the day before a business deadline — month end, stocktake, peak season. It is obvious written here and it is done regularly, because the date is chosen on the project’s calendar rather than the company’s.

The third is presence. Somebody from the supplier has to be reachable and available during the first days of real use, and that belongs in the contract rather than in a verbal promise.

The fourth is the way back. Write down before the switch what happens if it fails: who decides, at what point, and how you revert. A rollback plan that was never used cost nothing; its absence costs a day of downtime.

What we will refuse: pricing as a fixed sum a scope nobody has yet seen working. We can do it — it sells better — but the safety margin we would have to build in would cost you more than the method we propose instead.

We will also refuse to start with an eighty-page specification. We will ask for the rules, the edge cases you remember and what the tool will not do, then build the most frequent path and show it to you.

A limit of competence, stated plainly: we do not know your business. The rules come from you; we know how to ask the questions that bring them out, and how to tell an answer describing a habit from one describing a constraint, but we will not invent them.

What we do: rules written before screens, a first version reduced to the most frequent path, data migration tested against your real data in the first month, a named person on your side for acceptance, and a rollback plan written before the switch.

And what you should do without us this week: sit for an hour beside the person who will do the data entry and watch them work without interrupting. Note the three things they do that they have never described to anybody. Those are your rules, and they are worth more than the specification you were about to write.