How to describe what you need to a software team

Describing what you need to a software team means saying two things before any feature list: the conditions the work runs under, and what one row stands for. Leave a condition unsaid and the other side fills it in from whatever the product category assumes; the product name smuggles that assumption in. A unit described wrongly is not repaired by a later feature: features land on a row without changing which row owns what.

The list you wrote is probably not missing anything. Read on its own, it names a category of product, and two systems that behave nothing alike can answer it line for line. That is why adding another line does not close the gap. What is missing sits in front of the list. Keep the list. Put it in order.

A feature list names a product, it does not describe the work

Patient records, appointments, treatment plans, invoicing, reporting. That is roughly the list a dental clinic writes, and every item on it is correct. A general-purpose booking tool answers that list item by item. So does a system built around the clinic’s own way of working. The difference is not in the list; it is in which record each of those items sits on.

The clinic was running that arrangement on a general-purpose booking tool. What it wanted was not separate modules. It wanted the treatment plan, the appointment and the invoice to sit on the same patient record. The list was right and the thing that was ordered was wrong. There is no line item for that sentence either: “keep them on one record” is not the name of a feature, it is a decision taken when the system is set up. How the clinic’s record was put together sits on its project page; this article looks only at the gap between what was wanted and what was ordered.

Lengthening the list does not close that gap. “Treatment plan” was already on the clinic’s list. What was missing was not the name of the plan but whether the plan stands as a record in its own right or lives as a field inside an appointment. A list carries the names of things. It does not carry how those things attach to each other, and it never will, however long it gets.

A product name can also smuggle an assumption in with it. Say “staff entry and exit tracking system” and the category behind that name assumes a fixed turnstile at a fixed location. On a construction site the location is temporary, no turnstile goes up, and the crew moves between sites during the week. When a buyer names the product, that assumption is spoken along with it, without anyone noticing. What has been described is not the condition of the work; it is the condition of the category.

The opposite happens too. In some businesses the name of the product category really does describe the work, and the list is enough on its own. But you cannot find that out by staring at the list. You find it out by saying the condition and the record first, and looking afterwards.

The physical conditions of the work: where, on what device, over what connection, in whose hands

The condition of the work comes out in four questions. Where is it done, on what device, over what connection, in whose hands. You already know all four answers. What you do not know is that they need saying, and that each one closes off a design decision before anything is drawn.

When the answer to “where” is “on a temporary site”, the fixed-hardware option falls away at the start. Putting up a turnstile means taking it down again when the site closes. On the construction workforce project the record is therefore taken on the worker’s own phone, and when the site closes there is nothing left on it to dismantle.

When the answer to “in whose hands” is “crews move between sites, and several subcontractors work on the same site”, the record has to attach to a person and a site at once. A QR code says who scanned, location says which site they were on, and the two arrive inside a single entry record; nobody picks the site name from a menu. That link is made at the moment the record is created. It cannot be made afterwards by adding a site column, because the older records have no location inside them to read.

When the answer to “on what device” is “the worker’s own phone”, the application goes onto something the employee carries rather than something the business installs. Whether the business supplies the device or the worker brings it is a decision of its own, and we took it apart separately in the piece on choosing between an app and a mobile website.

The answer to “over what connection” is usually the last one anyone thinks to say. In service work the technician is in a boiler room or a lift shaft, and coverage stops there. Leave that sentence out and where the record is created stays undecided. How a record is created on the phone without a connection, and what happens once the signal returns, sits in the piece on field apps that work offline. What belongs here is the condition itself and nothing more.

The four questions do not bite everywhere. At the dental clinic the work happens in one place on a fixed computer, and connectivity is not a subject at all. The condition there is a matter of time: a treatment does not finish in one appointment, it breaks into sessions spread over weeks, and it changes in between. So the four questions are not a form to be filled in. “We have no connectivity problem” is an answer, and it locks a decision just as firmly. The trouble is never an unanswered question; it is an unasked one, because when the condition goes unsaid the other side reads it off the default condition of the product category.

What one row in the system stands for

The second sentence has one shape: “for us, one record is a …”. Its job is to name what a row in the system corresponds to in real life. It sounds trivial, because everybody assumes the answer is obvious. In three different businesses the answer turned out not to be the default record of the product category.

At the dental clinic a record is not an appointment. It is a treatment plan, built tooth by tooth and broken into ordered sessions. The plan stands on its own, independent of the calendar, and every appointment attaches to a particular step of it. Change a step or add a session and the calendar moves with it.

In service work a record is the device, not the customer. One address can hold more than one device, which is why the sentence the buyer needs to say is “for us, one record is a device, not a customer”.

In a perfume shop the product record is the fragrance, but the unit that gets sold is the bottle size. Price and stock attach to the size; adding a new size does not open a new product, it adds a unit under an existing fragrance. The word “product” is covering two different records at once here, and a buyer who says “a perfume website” has not yet said which of the two counts as one record. Left unsaid, a standard model treats every size as a separate product and the same fragrance appears in the catalogue several times over.

In all three the unit was read off the work rather than off the product name: the plan at the clinic, the device in service, the size in the shop. None of them is the default record of its category, which would have been the appointment, the customer and the product. You say the unit; fitting it to the record structure of a piece of software is our job. The test that tells a sellable unit from a browsing path, by asking what price and stock hang off, sits in the piece on modelling variants.

In some trades the unit has no name in the buyer’s own vocabulary. On a construction site nobody says “for us, one record is an entry-exit pair”; they say “worker pay”. Here the sentence has to name the source. Pay is not the record; it is produced from the records.

A wrongly described unit is not fixed by any feature

When the unit is described wrongly, every feature added afterwards lands on the wrong row. Describe a service record as a customer card and the histories of the devices at one address run together on that card. A “device” field added later only tags the new records; everything already written stays under the customer row. A feature is written onto a row. It does not change who owns the row.

How that history sits under the device is written up on AlgoKlima’s project page. This section is about what would have happened had the unit been described the other way.

The second failure shows up on the calendar side. Describe the unit as the appointment, and where a patient stands in the plan gets read off the calendar, what has been invoiced gets read off a ledger, and the month-end picture gets assembled somewhere else again. Adding an “invoicing module” writes the invoice into its own ledger rather than onto the patient record. As long as the invoice does not come out of the patient record, adding a module leaves the problem where it was.

The fix, then, is not a feature. It is the row itself changing. At the clinic the plan was set up as a record standing on its own, independent of the appointment, and the appointment was attached to it.

What a late correction costs is not the new screen. Opening a field is easy; changing which row every record written until that day belongs to is not, because the old rows never captured what the new one needs.

Not every wrong description is permanent, though. A wrongly described feature does get fixed later: a report is the same patient record read from a different angle, and adding a column does not disturb the record. The two that do not get fixed are the condition and the unit.

Four pieces of work in three sentences

The table below puts four pieces of work side by side. The sentences in the first column are not quotations from anyone; they are what the opening sentence tends to sound like in a first meeting. The service row has no buyer at all: AlgoKlima is our own product, one we keep developing, and the sentence there is simply what the trade calls the thing.

The axis to read this table on is not a removed step or a preserved feature. It is the sentence itself. All four opening sentences name a category of product. None of the four unit sentences is that category’s default record. The gap between those two columns is exactly the gap a list, sent on its own, leaves open.

You can also read the table against your own work. Whichever row yours resembles, write your own sentences in the same order: the list or product name you already have, then where and in whose hands the work is done, then what one record stands for. If the third sentence contradicts the first, that contradiction sits in your business, and it is precisely the thing a software team needs to hear.

The condition sentence does not have a fixed shape either. In two of these it is built out of device and connection, at the clinic out of time, in the shop out of the state the customer is in when deciding. Which of the four questions bites depends on the work, and there is no requirement that all of them do.

What you no longer need to say once those two are said

Once the condition and the unit are described, items drop off the list.

Nobody asks for a “pay module”. With the entry-exit pair described as the unit, pay is not kept in a separate calculation sheet; it is produced from matched records, and time on different sites is totalled separately. Nobody asks for a “site picker” either. Once the condition says crews move between sites, the site name arrives from location and there is no menu to choose from.

Nobody asks for an “invoicing module” or a “reporting module”. Because the procedure performed sits on the patient record, the invoice and the report are both that same record read from another angle, and no separate ledger has to be opened. That is what the clinic wanted in the first place.

And “make it work offline” is not a feature item at all. It is the condition sentence. Once someone has said that coverage stops in the boiler room, a record being created on the phone stops being an add-on somebody requested and becomes where the design starts.

How a system decides on its first day which record is the source and which one comes out of it is written up in the piece on architecture coming first. All this section shows is that the derived items fall outside what you have to describe.

What to bring to the first meeting

Here is the preparation you can actually hold: describe one working day. Which site does the crew go to in the morning, does entry go onto a paper timesheet, does anyone move to another site during the week, how does the month-end total of who worked where and for how long get put together, and what is the evidence when someone disputes it. That account carries all four questions and the unit sentence on its own, and the word “attendance system” never appears in it.

A day on its own is not enough. Things that happen once a year, a dispute or an audit, are invisible inside a single day. That is why the account gets two extra questions bolted on: what is totalled at month end, and what the evidence is when the total is challenged. Both of them say more about what the record has to do than the day itself does.

Then there are conditions no feature list would ever hold. In a perfume shop the customer decides without being able to smell the product, and part of the buying is done as a gift for someone else. Those are not the names of features; they are conditions of the work, and a list has nowhere to put them.

Then the single sentence: “for us, one record is a …”. On the construction site that sentence reads “who, on which site, for how long”. When the feature list arrives after those two, the other side of the table stops reading it as the name of a product and starts reading it as items to be written on top of a condition and a unit. The list is doing the same job. It is just standing in a different place in the queue.

Say what conditions the work is done under and what a single row stands for in your business, and everything else gets written on top of those two sentences. Where those decisions are taken, before any code, is set out on our system architecture page, and how the record then runs inside a live system on our business process tracking page.