A definition of done has a narrow job. Six weeks from now, two people may disagree about whether something has been delivered. The document should settle that disagreement without either person raising their voice.
That is a demanding standard. Most scope documents fail it because they were written to get a signature rather than to be used later. They describe intent beautifully, but they do little to decide a disagreement.
A good line can be judged without argument
Take any line in your scope document and apply one test. Could two reasonable people read it and reach different conclusions about whether it has been delivered? If yes, you have a description rather than a definition.
"The system will provide comprehensive reporting" fails immediately. Different people will read "comprehensive" in different ways. One person may think it means a dashboard. Another may expect exports, filters, charts and scheduled emails.
"Users can export the transactions list for a date range they choose, as CSV, with the eleven columns listed in appendix B, in under ten seconds for a range of up to one year" cannot be argued about in the same way. It is longer and less elegant. It also does the job.
The document needs to cover the work from several angles
Our definition of done is built section by section. Each section exists because a different kind of ambiguity causes problems during delivery or acceptance.
The main sections are these:
- The behaviours. Things a person can do, with the specifics that matter.
- The data. What is stored, what is required, what happens to existing data, and what the migration produces.
- The interfaces. Every system this one talks to, in which direction, with whose credentials, and what happens when the other side is unavailable.
- The numbers. Performance targets, capacity, availability if there is a commitment, and accuracy where a model is involved.
- The boundaries. An explicit list of what is included outside the scope.
- The environments. What exists, who provides it, and by when.
- The acceptance procedure. Who tests, against what, for how long, and what counts as a defect versus a change.
- The assumptions. Checkable statements with dates and defined consequences if they fail.
Behaviours describe what people can actually do
The behaviours section is written as actions a person can take. We avoid broad feature labels because they hide the real decisions. "Invoice management" sounds useful, but it does not say enough to settle anything.
A useful line gives the actual list of what may be done to an invoice, by whom, and what happens to it. That is the level of detail that lets both sides look at the finished system and agree whether the behaviour exists.
Data is where overruns often start
The data section says what is stored, what is required, what happens to existing data, and what the migration produces. This section is nearly always underwritten. It is also nearly always where the overrun comes from.
That happens because data work contains decisions that are easy to miss in conversation. Existing records may need to move. Required fields may need to be agreed. A migration may need a defined output before anyone can say it has succeeded.
Interfaces include the systems people call trivial
The interfaces section names every system this one talks to. It says which direction the connection works in, whose credentials are used, and what happens when the other side is unavailable.
That includes the systems the client considers trivial. A small connection can still block acceptance if nobody agreed what should happen when the other system is down.
The numbers belong in the main body
The phrase non-functional does a lot of damage. It suggests these requirements are secondary, and it pushes them into an appendix nobody prices.
A performance target, an availability commitment or a security control frequently determines the architecture. Architecture determines cost. A system serving a hundred concurrent users and one serving forty thousand are different systems, rather than the same system with different hardware. Discovering that in month three is expensive.
For that reason, the numbers go in the main body with the behaviours. Performance targets are expressed as percentiles rather than averages, against a stated data volume. Capacity is stated. Availability is stated where there is a commitment. Accuracy is stated where a model is involved, against a named evaluation set.
If the client cannot tell us the concurrency, establishing it becomes part of the investigation phase. We do not absorb it as a guess.
The boundaries prevent the most arguments
The boundaries section is the part to write carefully. It is where the difference between a fixed price that works and one that becomes a dispute actually lives.
Clients often want to shorten this section. It is also the section that prevents the most arguments, because it gives a clear list of what is outside the work.
Ours typically includes exclusions like these:
- This does not include changes to the existing accounting system.
- This does not include data cleansing of records prior to 2019.
- This does not include mobile applications, only a responsive web interface.
- This does not include training materials beyond the runbook.
- This does not include support for browsers more than two years old.
- This does not include the migration of the third legacy system mentioned in the workshop.
Each of those lines is there because it was ambiguous in a conversation. Writing it down is the mechanism by which the client can see what they are not getting, in time to ask for it.
Acceptance has to separate defects from changes
The most reliable source of conflict in any fixed price engagement is the boundary between a defect and a change. A defect is fixed at our cost. A change is priced separately. Left undefined, every disagreement becomes a negotiation about goodwill.
Our rule is simple enough to apply without a lawyer:
- If the behaviour differs from what the definition of done says, it is a defect.
- If the definition of done is silent and the client wants a particular behaviour, it is a change.
- If the definition of done says something the client now realises they did not want, it is a change.
The second and third cases can feel harsh when written down. They are fair, because the alternative is that the supplier absorbs unlimited scope discovered after signature. Suppliers will price that into every future proposal.
The acceptance procedure is agreed before anyone starts. It says who tests, against what, for how long, and what constitutes a defect versus a change. Agreeing it afterwards means negotiating under pressure.
The supplier should draft it and the client should mark it up
We write the definition of done, and the client marks it up. The reverse produces a worse document. Clients write requirements in terms of the outcome they want. Suppliers need to write in terms of what will be built. The ambiguity hides in the translation between those two views.
The review matters more than the authorship. We ask the client to have it read by somebody who will use the system, rather than only by the person who commissioned it. That reader finds different things, and finds them earlier.
Keep it short enough that people read it
There is also a failure mode at the other end. A two hundred page specification can contain every possible detail and still adjudicate nothing, because nobody reads it.
Ours are usually between eight and twenty pages. The discipline that keeps them short is to write only what is decidable. A line belongs in the definition when it can settle an argument about delivery.
Descriptions of context, rationale and background belong elsewhere. They cannot settle an argument, and their presence dilutes the parts that can.
Use it during delivery, not only at the end
The document is not filed after signature. It is the reference for every demo and every acceptance conversation. When we complete a piece of work, we say which lines it satisfies.
That habit has a useful side effect. It surfaces lines that turn out to be wrong, early, while there is time to change them by agreement.
A definition of done that is never referenced until the final acceptance meeting will be read for the first time by two people who already disagree. That is the situation it was written to prevent.
A vague notification line becomes a delivery test
It helps to see one line go through the process. The improvement becomes obvious when you watch an ambiguity get removed.
The original, from a client’s brief, was this: the system should notify managers of unusual activity.
Six questions later it became this: when a transaction exceeds either the account’s ninety day rolling average by four times or a fixed threshold set per account, an email is sent to the account’s assigned manager within five minutes, containing the transaction reference, amount, account and a link to the record. If no manager is assigned, it goes to the operations mailbox. Notifications are not sent between 22:00 and 06:00 and are batched into a single digest at 06:00 instead. A manager can mark a transaction as expected, which suppresses further notifications for that counterparty for ninety days.
Nobody enjoys writing the second version, and it takes about twenty minutes. Every clause in it corresponds to a decision that would otherwise have been made silently by a developer at some point. That decision would probably be different from what the client assumed, and it would be discovered during acceptance.
Some lines need an expiry date
Some parts of a definition are true only for a period. Saying so prevents an argument later.
Browser support is the obvious one. A commitment to browsers current at the time of writing is reasonable. A commitment to browsers current forever is not reasonable, because the target moves without either party doing anything.
The same applies to third party interfaces. If we integrate against version three of an API, the definition says version three. When the provider deprecates it, that is new work. Both parties knew that in advance rather than discovering it in an awkward conversation.
It also applies to any dependency on a model provider, where the behaviour we measured is the behaviour on a stated version at a stated date.
Writing the expiry into the document converts a future surprise into a scheduled event that somebody can budget for.
The written boundary makes the relationship easier
The unexpected effect of working this way is that the conversations get better. They become less legalistic, because the boundary is written down and nobody has to defend it in the moment.
Requests that would previously have been made obliquely get made plainly. A client who knows exactly what is included will ask directly for the thing they want added, and we can price it in an afternoon.
A client who is unsure will hint, and hedge, and try to get it folded in, because they are worried about being told no. The document removes that whole layer of diplomacy. What is left is two parties talking about the work.
Skipping it makes the project slower later
Occasionally a client wants to skip this. They are in a hurry, they trust us, and the document feels like bureaucracy delaying the start.
We have learned to decline. That comes from experience, rather than principle. Every engagement that started without an agreed definition ended in a difficult conversation. In each case, the difficulty was not that anybody behaved badly. Two groups of reasonable people had different pictures in their heads, and no artefact could adjudicate between them.
The way we put it now is that we are happy to move quickly. The fastest route to starting is two days of writing this down, because the alternative is a project that stops in week six while everybody works out what was meant.
The client gets a clearer way to hold the supplier to the work
This is not primarily supplier protection. A client with a written definition of done can hold a supplier to something specific. They can compare two proposals on equal terms. They can tell whether they have received what they paid for without relying on the supplier’s assessment.
The absence of one benefits whoever is more comfortable with ambiguity, and that is almost never the buyer.
More on the commercial model in engagement models, and on the delivery method in how we work.
