Most requirements documents in Pakistan are a list of features and a set of screenshots from a competitor. They feel like preparation and they prevent almost nothing, because a feature list does not say what the software must do when something goes wrong, who is allowed to do what, or how anyone will know it is finished.
Here is what actually belongs in the document, in the order it is worth writing.
1. The problem, in one page
Not the solution. What is happening now, what it costs, and what would be different if this worked.
“Orders arrive on WhatsApp and are copied into a spreadsheet by two people. About one in twenty is entered wrong, and we discover it at dispatch. Reconciling stock takes a day a week.”
That paragraph tells a developer more than thirty feature bullets, because everything they design can be tested against it. Teams that skip this section build features nobody needed.
2. Who uses it, and what each is allowed to do
List every role, and for each one: what they can see, what they can create, what they can edit, and what they must never be able to do.
This section prevents the single most expensive category of rework. Retrofitting a permission model into a system that assumed one kind of user is close to a rebuild. Write it before anyone writes code, even if it feels premature.
3. The main workflows, start to finish
For each core process, write the steps as a sequence: the person does this, the system does that, then this happens.
Then, for each step, ask what happens if it fails. What if the payment is declined. What if the customer closes the browser halfway. What if two people edit the same record. What if the courier API is down.
The failure cases are where the real requirements live, and they are the most common source of change requests during a build. Fifteen minutes per workflow spent on failures saves weeks.
4. The data
What records exist, what fields each has, and how they relate. You do not need a database diagram. You need to have decided that a customer can have many addresses, that an order belongs to one customer, and whether a product’s price is stored per branch.
Include units of measure, currency handling and anything with a date, because those three are the most frequent sources of expensive misunderstanding.
5. Integrations, individually
Every external system: payment gateway, courier, SMS, WhatsApp, accounting, ERP, FBR digital invoicing. For each one, note whether you already have an account, whether credentials exist, and who at your organisation owns that relationship.
Integrations are the largest driver of both cost and delay in most projects, and the delay is usually commercial onboarding rather than engineering. Starting the account setup in week one is the cheapest schedule saving available.
6. Acceptance criteria
The section that turns a document into a contract. For each major feature, how will you know it works.
Weak: “The system should generate reports.”
Better: “A branch manager can produce a stock movement report for a date range, filtered by category, exportable to Excel, in under ten seconds for a 5,000 item catalogue.”
Written this way, nobody argues at handover about whether something is done. This is also the section that protects the developer, which is why good agencies ask for it.
7. What is explicitly out of scope
The most valuable and most often missing section. Write down what this project is not doing: no mobile app in phase one, no multi currency, no integration with the old system, reports limited to these five.
Being explicit here is not defensive. It is how both sides avoid discovering a different understanding in month three.
What to leave out
- Technology choices, unless you have a real constraint such as existing infrastructure or an internal team that must maintain it. Otherwise you are limiting the solution before understanding the problem.
- Detailed screen designs. Describe what a screen must let someone do, not where the buttons go. Design is a specialist job that should happen after requirements.
- Aspirational features. Anything you might want in two years belongs in a separate list, not in the scope for this build.
How long should it be
For a mid sized business system, ten to twenty pages is normal and sufficient. Documents over fifty pages are usually padded with things nobody will read, and the important decisions get lost inside them.
If you cannot write it, that is useful information rather than a failure. It usually means the process is not yet agreed internally, and no software project should start before that is settled. A short paid discovery phase with your development partner is the normal way to resolve it, and it is far cheaper than discovering the disagreement in month three. Our note on contract models explains where that phase fits.
A structure you can use today
- The problem and what success looks like
- Users and permissions
- Core workflows, including failure cases
- Data and relationships
- Integrations and who owns each account
- Acceptance criteria per feature
- Out of scope
- Constraints: budget, deadline, compliance, existing systems
Frequently asked questions
Who should write the requirements document?
Someone from the business who understands the process, with help from the development partner on structure. Written entirely by the agency it will reflect their assumptions; written entirely by the business it will usually miss the failure cases.
Do I need one for a small project?
A two page version, yes. Users, workflows, acceptance criteria and out of scope. Even a brochure website benefits from a written list of what is not included.
What if requirements change during the project?
They will. The document is a baseline, not a cage. What matters is having an agreed change process with a price attached, so changes push the date or the cost deliberately rather than silently.
Should I include screen designs?
Reference examples are useful for communicating intent. Detailed designs before requirements are settled usually get thrown away.
Ezitech runs a short discovery phase before any build, producing exactly this document plus wireframes and a realistic estimate. See how we scope projects.