Writing Software Requirements as a Business Owner: User Stories That Work
Write software requirements as short user stories that say who needs what and why, each with acceptance criteria that say how you will check it works. Rank them with MoSCoW priorities, so the essentials are clear. Add a short list of qualities the whole system needs: languages, devices, speed, security, data retention and integrations. Describe the need and the test, not the screen. A developer can then build it, quote it and prove it works.
This format is not bureaucracy. It is the cheapest way to make three suppliers quote the same thing, and to settle arguments at sign-off by pointing at a sentence everyone agreed.
The short answer
- User story: “As a [role], I want [something], so that [benefit].”
- Acceptance criteria: “Given [situation], when [action], then [result]”, written for the normal case and the exceptions.
- Priorities: Must have, Should have, Could have, Won’t have this time.
- System qualities: Arabic and English, devices, response times, access control, audit trail, retention, hosting, integrations.
- Leave out: screen designs, technology choices and vague words like “fast” or “user-friendly” without a measure.
Why requirements go wrong
Most requirement documents fail in one of two ways. Some are a wish list of features with no reasons, so nobody can tell which matter. Others describe screens and buttons in detail, so the supplier builds exactly what was drawn, including the parts that were wrong.
Both miss the two things a developer needs: the purpose of each feature, and a way to know when it is done.
User stories: who, what and why
The user story format, “As a… I want to… So That…”, is known as the Connextra format after the British company where it was invented in 2001, according to the Agile Alliance. Each story fits in one sentence:
As a branch manager, I want to approve purchase requests below OMR 500 from my phone, so that orders are not held while the general manager is travelling.
The “so that” part is the most important and the most often skipped. It tells the developer what problem the feature solves, which lets them suggest a simpler way to solve it.
A useful check is INVEST, a checklist from a 2003 article by Bill Wake that the Agile Alliance describes as “a widely accepted set of criteria” for assessing a user story. A good story is Independent, Negotiable, Valuable, Estimable, Small and Testable.
Acceptance criteria: how you will know it works
Each story needs criteria that can be tested. The Given–When–Then template, which the Agile Alliance describes as “intended to guide the writing of acceptance tests for a User Story”, works well:
Given a purchase request of OMR 450 from a storekeeper at my branch, when I approve it, then its status becomes Approved, the storekeeper is notified, and the approval is recorded with my name and the time.
Then write the exceptions, because that is where systems succeed or fail:
Given a purchase request of OMR 600, when I open it, then I can view it but not approve it, and it is routed to the general manager.
These criteria become your test cases at sign-off. User acceptance testing explains how to use them.
Priorities: be honest about what is a “must”
Mark every story with a MoSCoW priority: Must have, Should have, Could have, or Won’t have this time. The method comes from the DSDM framework, now maintained by the Agile Business Consortium, which advises keeping Must Have work to typically no more than 60% of the effort, with a pool of Could Haves of around 20%.
The discipline matters more than the percentages.
“If everything is a must, nothing is. The first thing to slip when time runs short will then be chosen by accident, not by you.” — Abdulqader Wahiba, founder and CEO of ZAWAT
Scoping the first version explains how to decide what is truly essential.
System qualities: what applies to everything
Some requirements are not features but qualities of the whole system. Write them once:
- Languages: Arabic and English, with right-to-left layout, Arabic sorting and search. Building bilingual Arabic-English software lists what that involves.
- Users and devices: how many people, in which roles, on which devices.
- Speed: for example, “search results appear within two seconds for 95% of searches”. Use a number.
- Access and audit: who can see and change what, and a record of who did it. Access control and audit trails covers the design.
- Data retention: for invoices and accounting records, Article 70 of the VAT Law requires ten years after the end of the tax year of the return, and fifteen for real estate.
- Personal data: what you hold about people, and how the system supports Oman’s data protection law. Privacy by design covers the decisions to make early.
- Integrations: every system it exchanges data with, in which direction, and how often.
- Hosting: where the data may live. Cloud hosting rules in Oman explains the constraints.
Weak and strong requirements, side by side
| Weak | Strong |
|---|---|
| “The system should be fast.” | “Search results appear within two seconds for 95% of searches.” |
| “Add a dropdown for the branch.” | “As a storekeeper, I want my branch filled in automatically, so that I can’t file a request under the wrong branch.” |
| “Managers approve requests.” | “Branch managers approve below OMR 500; above that, requests go to the general manager.” |
| “Support Arabic.” | “Every screen, email and PDF is available in Arabic and English, with right-to-left layout in Arabic.” |
| “Reports as needed.” | “As the finance manager, I want monthly purchases by branch exported to Excel, so that I can reconcile them with the ledger.” |
A one-page template
For each process in scope, one page is usually enough:
- Process and purpose: one sentence, linked to your process map.
- Users: the roles involved.
- Stories: five to fifteen, each with a MoSCoW priority.
- Acceptance criteria: for each Must and Should story, the normal case and the main exceptions.
- Open questions: what you have not decided yet, and who decides.
Add one page of system qualities for the whole project, and you have a brief a competent supplier can quote. Give the same brief to every supplier, as choosing a software partner in Oman recommends, and their prices become comparable.
Frequently asked questions
Do I need a full specification before getting quotes? No. A clear set of prioritised stories with acceptance criteria for the essentials is enough for a ranged estimate. Detail grows as the project proceeds, and a discovery phase can produce it with you.
Who should write the user stories? The people who own and do the work, with help from whoever runs the discovery. Stories written only by management or only by the supplier tend to miss the exceptions.
How many user stories does a business system need? It depends on the scope. A single process might need ten to twenty; a multi-department system, many more. Count is less important than coverage of the real cases.
What does ZAWAT recommend owners write themselves? Abdulqader Wahiba, ZAWAT’s founder and CEO, advises owners to write the need and the test, and to leave the screens to the people being paid to design them. If you can state who needs what, why, and how you will check it, you have done your part.
Can requirements change after the contract is signed? They will. Agree in advance how changes are handled: how they are estimated, who approves them, and what moves out of scope to make room. Treating every change as a dispute is as harmful as accepting every change without a price.
Sources: Agile Alliance — User Story Template (Connextra format) · Agile Alliance — INVEST · Agile Alliance — Given-When-Then · Agile Business Consortium — MoSCoW prioritisation · Value Added Tax Law, Royal Decree 121/2020, Article 70
Want help turning your process into requirements a supplier can quote? This is the work ZAWAT’s Discover step is for, in custom software and business systems. Book a call.