How to write a software scope that two engineers would build the same way

A proposal describes outcomes. A scope describes decisions. If two competent engineers could read your document and build different things, it is not a scope yet — and the gap between them is where the budget overrun lives.

What belongs in it

Five things. Everything else is commentary.

1. 01The workflows, step by step, including the exceptions. Not "order management" but the actual sequence: who starts it, what they enter, who approves, what happens when approval is refused, what happens when the approver is on leave.
2. 02Who can see and do what, by role. Named roles with explicit permissions. Not "role-based access control", which is a technology choice, but the actual matrix.
3. 03The data model at entity level. What a customer is. What an order is. Whether a site belongs to a customer or stands alone. The relationships, not the column types.
4. 04Every integration, named, with its direction. Which system, which data, flowing in or out or both, how often, and what happens when it is unavailable.
5. 05What is explicitly out. The shortest section and the most valuable one.

What does not count

These appear in most documents labelled as scope and decide nothing:

• "A modern, intuitive interface." Every interface is intended to be this. It constrains no decision.
• "Scalable architecture." Scalable to what, measured how, by when. Without numbers it is a mood.
• "Full ERP suite." A category, not a requirement.
• A feature list with checkmarks beside it. Features are the output of decisions; listing them skips the decisions.
• Screenshots of a competitor's product. Useful as reference, useless as specification, because you cannot see their exception handling either.

A good test: delete every sentence that nobody could disagree with. What is left is your actual scope. If that is two pages, you have two pages of scope and a lot of hopeful prose.

Writing the exceptions down

This is the part that separates documents that hold from documents that do not, and it cannot be done from a desk. The exceptions live with the people doing the work, and they will not volunteer them, because to them they are not exceptions — they are Tuesday.

Three questions get most of them out:

1. 01When was the last time you had to do this differently, and what did you do?
2. 02What do you do when the person who normally approves this is away?
3. 03What is the thing you have to remember that the current system does not help with?

Write the answers into the workflow as named paths, not as a footnote. An exception recorded as a footnote gets built as a footnote, which is to say not at all.

Naming every integration and its direction

Integrations are where estimates break, because they are counted as one line and behave like several. For each one, write down five things: the system, the data, the direction, the frequency, and the behaviour when the other side is down or slow.

That last one is the one that gets skipped and the one that generates support tickets for years. "The accounting system is unreachable at 9pm during their backup" is a requirement, whether or not anyone wrote it down.

Saying what is out

An out-of-scope section protects both sides, and most of its value is on yours. Without it, every conversation about something new starts from an argument about whether it was always implied.

Be specific. "Reporting is out of scope" invites trouble. "Scheduled PDF reports by email are out of scope for phase one; the on-screen dashboards listed in section 4 are in" does not.

A structure you can start from

This is roughly the shape we use. It is deliberately unglamorous.

1. 01Context. What the operation does and what is failing now. Half a page, no marketing.
2. 02Entities. Each one defined in a sentence, with its relationships to the others.
3. 03Roles and permissions. A table. Rows are roles, columns are actions.
4. 04Workflows. One section each. Steps numbered, exceptions as named sub-paths, with the role that performs each step.
5. 05Integrations. One row each: system, data, direction, frequency, failure behaviour.
6. 06Reports and outputs. What must be produced, who reads it, how often.
7. 07Non-functional requirements with numbers. Concurrent users, data volumes, response expectations, retention periods, anything regulatory.
8. 08Migration. What history is coming across, from where, in what condition.
9. 09Explicitly out of scope. The list, with phase markers where relevant.
10. 10Open questions. The things you have not decided, named rather than hidden.

That last section is the sign of an honest document. Every scope has open questions at the point of signing. The ones that cause damage are the ones that were open and presented as settled.

The two-engineer test

Before you send it anywhere, hand each workflow section to two people who were not in the discussions and ask them to describe what they would build. Where their answers differ, the document is ambiguous, and the ambiguity will be resolved later by whoever is cheapest to ask rather than whoever knows the business.

A scope that survives that test is also the document you should be scoring vendors against, which is why it is worth writing before you start talking to any of them. The questions to put alongside it are in questions to ask a software vendor, and what it does to your estimate is covered in what does a custom ERP system cost.

If you would rather talk it through than write it cold, that conversation is most of what our discovery work is, and you can start it from the contact page.