A brief is written to get quotes. A scope document is written after a supplier has been chosen, and it does a different job: it records what both sides now believe is being built, in enough detail that either can tell when it is finished.
That last part is the whole value. Almost every disputed final invoice comes down to one sentence: this is not what we agreed. Almost every instance of that sentence traces back to a scope document that either did not exist or described the work in terms too general to check.
A good scope document is boring to read and cheap to argue with. Both are the point.
Who writes it, and when
The supplier writes it, after understanding the process and before the build. The client reads it properly, in one sitting, with the people who do the actual work in the room.
That ordering matters. A scope written by a client before a supplier has looked at anything is a brief wearing the wrong name, and it locks in assumptions nobody has tested. A scope written by a supplier without access to the people who do the work will describe the official process, which is reliably different from the real one.
The reading is not a formality. It is the last cheap opportunity to find a misunderstanding, and it is worth taking an hour over. Somebody in that room should be reading with the intention of finding something wrong.
The eight sections
| Section | What it settles |
|---|---|
| Objective | Why this is being built and what will be true afterwards |
| In scope | What will exist, described as capability rather than screens |
| Out of scope | What deliberately will not exist, including obvious-seeming things |
| Users and permissions | Who uses it and what each role may see and do |
| Key flows and states | How the important objects move, and what states they occupy |
| Integrations and data | What connects to what, which direction, and which system is the authority |
| Assumptions and dependencies | What is being taken as true, and what the project needs from you |
| Acceptance | How both sides will agree it is done |
Four of those are where the document earns its keep.
Out of scope
Counterintuitively the most valuable section, and the one clients most often skim.
It should include things that seem obviously excluded, because "obviously" is doing dangerous work in that sentence. If the project does not include migrating historical data, say so. If it does not include training, say so. If reporting means three specific reports and not an ad-hoc report builder, say that too.
A useful test: read the out-of-scope list and check whether any item makes you uncomfortable. That discomfort is the document working. It is far cheaper to feel it now than in the week before launch.
Key flows and states
The section that most often gets left out, and the one that most reliably predicts whether the estimate was sound.
For each important object, whether that is an order, a booking, an application, a case or an invoice, the scope should list its possible states and who may move it between them. Prose is not adequate here; a small table or diagram is. Ten lines of table will surface disagreements that ten pages of description will hide.
This section is also where you discover whether the supplier has understood the business. If the states in the document do not match how the work behaves, something has been misread, and it is visible now rather than in month four.
Assumptions and dependencies
Assumptions are what the estimate depends on: that content will be supplied by a date, that the existing data export is complete, that the third-party interface behaves as documented, that no more than a stated number of user roles exists.
Write them down even when they feel trivial. An assumption stated is a shared risk; an assumption unstated is a future argument. The good faith version of this section is short and specific, and each item should be one that would visibly change the work if it turned out false.
Dependencies are what the project needs from the client and by when: decisions, access, content, test data, someone available for questions. Naming them converts "the project is late" into a conversation both sides can have without blame, because it is clear what was needed and when.
Acceptance
The section that decides whether the final invoice is paid without argument.
Acceptance criteria should be written so that a non-technical person could check them. Not the booking module will be complete, but a customer can book an available slot, receive a confirmation email, and cancel it up to 24 hours before, and a cancelled slot becomes available again. That is checkable by anyone, in five minutes, with no interpretation required.
Three practical rules. Write acceptance criteria before the build, not at the end, because criteria written afterwards describe what was built. Include the awkward paths as well as the ideal ones — what happens when the slot is taken while the customer is typing. And agree how long the acceptance period runs and what happens to defects found inside it, which is usually where the remaining ambiguity lives.
A worked example
Take one feature: customers can book appointments. Here is roughly what an adequate scope entry looks like, condensed.
In scope. A logged-in customer can view available slots for the next 60 days, book one, and receive an email confirmation. They can cancel or reschedule up to 24 hours before the start. Staff can view the day's bookings, mark attendance, and create a booking on a customer's behalf.
Out of scope. Recurring bookings. Payment at the time of booking. SMS notifications. Waiting lists. Multiple locations — the system assumes one.
States. A booking is requested, confirmed, cancelled by customer, cancelled by staff, attended or missed. Only staff may set attended or missed. A cancellation returns the slot to availability; a missed booking does not.
Assumptions. Slot availability comes from one staff calendar, maintained by the client. Email delivery uses the client's existing provider. No more than 200 bookings a day.
Acceptance. A customer books, receives confirmation within two minutes, cancels 25 hours ahead successfully, is prevented from cancelling 23 hours ahead, and the cancelled slot appears as available. Staff can mark yesterday's bookings attended or missed.
That is around 200 words, and it removes more risk than several pages of description would. Note what it did: it named the exclusions that would otherwise be assumed, fixed the states, surfaced the single-location assumption, and turned "done" into something checkable in a few minutes. Everything above is illustrative rather than a template to copy directly.
What does not belong
Screen designs. The scope says what must be possible. Designs decide how, and putting them in the scope freezes the interface before anyone has learned anything from building it.
Technical implementation. Which framework, which database, how the code is structured. Those are the supplier's decisions to make and explain. A scope that specifies them is either a client overreaching or a supplier padding the document.
The brief, pasted in. The scope supersedes the brief. Including both creates two documents saying overlapping things, and the first serious disagreement becomes an argument about which one governs.
Every screen listed individually. Screen inventories belong in the structure stage. A scope that lists 40 screens is guessing at 40 screens before the flows are settled, and will be wrong about several.
Keeping it honest during the build
Scope documents go stale. Things get learned, better ideas surface, one assumption turns out false. The failure is not the change but the change going unrecorded, so that two versions of the truth exist by month three.
A workable arrangement: a short, unceremonial change note for anything that alters the agreed scope, saying what changed, why, and what it does to time and cost — even when the answer is nothing. Two sentences is usually enough. The purpose is not bureaucracy; it is that in month five nobody has to reconstruct from memory when the second user role appeared.
Small clarifications do not need this. Anything that adds a state, a role, an integration or a screen does.
Common questions
How long should it be? As long as its states and exclusions require. Small projects can be settled in four or five pages. Large ones run longer, but if it is unreadable in one sitting, it will not be read properly, and an unread scope provides no protection at all.
Is it the same as a contract? No, though it is usually attached to one. The contract covers payment, ownership, liability and termination. The scope covers what is being built. Both should say the same thing about deliverables, which is worth checking, because they are frequently written by different people.
Who pays for producing it? On most projects, writing a proper scope is real work, often several days of examining the process, and it is normally a paid stage. That is reasonable, with one condition worth insisting on: the document should be usable by another supplier if you decide not to continue. A scope you cannot take elsewhere is a lock-in, not a deliverable.
What if the supplier does not offer one? Ask for one. If the answer is that it is unnecessary for a project this size, ask instead how you will both know when it is finished. The answer to that question tells you whether the document was genuinely unnecessary or simply not going to be written.
The short version
- The scope is written after a supplier is chosen and before the build, by the supplier, read properly by the people who do the work.
- Eight sections: objective, in scope, out of scope, users and permissions, flows and states, integrations and data, assumptions and dependencies, acceptance.
- Out of scope is the most valuable section. If nothing on the list makes you slightly uncomfortable, it is not complete.
- States belong in a table, not in prose. They are the best available check on whether the estimate was sound.
- Acceptance criteria should be checkable by a non-technical person in minutes, and written before the build rather than after it.
- Keep designs, technical implementation and the original brief out of it.
- Record changes as they happen in two sentences, so there is one version of the truth at month five.
Where to take this next
If you have not chosen a supplier yet, the earlier document is the one to write: how to write a project brief a developer can actually price. And if the scope is being written now, what to work out before you ask anyone to build software lists what you should bring to the conversation that produces it.
The stage that produces this document is where most of a project's risk is removed, which is why how we work puts it before anything gets built.
# Visual recommendations
Concepts only. Hairline drawing, ink and brass.
Hero visual — the two documents
Concept. Two document outlines side by side with an arrow between them. The left, labelled brief, is annotated written to get comparable quotes and shown with soft, open edges. The right, labelled scope, is annotated written to define done and drawn with a hard edge and a small tick block at its foot representing acceptance criteria. Between them, a small marker on the arrow reading supplier chosen.
Purpose. Most readers arrive confusing the two documents. The hero separates them before the article begins.
Alt text. A brief, written to get comparable quotes, leads to choosing a supplier, which leads to a scope document written to define when the work is done.
Supporting visual — a booking's states
Concept. A state diagram of the worked example: requested to confirmed, with branches to cancelled by customer and cancelled by staff, and from confirmed to attended or missed. Transitions restricted to staff are drawn in brass; transitions returning a slot to availability carry a small return arrow.
Purpose. Demonstrates the article's claim that ten lines of state diagram do more than pages of prose, by being visibly small and visibly complete.
Placement. Inside the worked example, replacing or accompanying the states paragraph.
Alt text. A booking moves from requested to confirmed, then to attended or missed, with cancellation paths available to both customer and staff, and staff-only transitions marked separately.