Writing System Requirements That Vendors Cannot Misread
Many system disputes start with a sentence both sides read differently. Here is how to write requirements that are specific, testable and hard to misinterpret.
“The system should support multi-branch inventory.” Every vendor who reads that sentence will say yes, and every one of them will mean something different. Six months later, the client discovers that “support” meant separate stock figures per branch, but not transfers between them, not branch-level pricing, and not a consolidated view for head office.
Many disputes between companies and their software vendors start with requirements written loosely enough for both sides to read them their own way. Writing system requirements that hold up is a skill any manager can learn.
Why vague requirements are so common
Requirements are usually written by busy managers who know their business so well that they skip the details. To them, “multi-branch inventory” is obvious, because they live with it every day. The vendor, who has never seen your warehouse, fills the gaps with whatever their product already does.
There is also a temptation to describe the solution rather than the need. “We need a dashboard” says little. “The sales manager needs to see, every morning, which customers have overdue balances above their credit limit” tells the vendor what problem to solve and lets them propose the best way.
The anatomy of a requirement that holds up
A strong requirement answers five questions. If any of them is missing, the requirement is open to interpretation.
- Who performs or needs this? Name the role, not “the user”. A branch storekeeper and a head-office controller need very different things from the same screen.
- What do they need to do or see? Use an active verb: create, approve, transfer, view, export.
- When or how often does it happen? Daily, at every order, at month-end, on request.
- Under what rules? Thresholds, approvals, exceptions, validations. This is where most of the real complexity lives.
- How will you know it works? A short acceptance test that anyone can run during testing.
Before and after: rewriting real-world examples
Consider a private school network with four campuses in Amman and Zarqa, choosing a new student information and fees system. Here is how some of their first-draft requirements could be rewritten.
| Vague version | Version a vendor cannot misread |
|---|---|
| The system should handle sibling discounts. | When a family has two or more children enrolled across any campus, the system applies a discount per child based on birth order, using a discount table that head office maintains. The discount appears as a separate line on each invoice. Test: enrol three siblings at two campuses and confirm each invoice shows the correct line. |
| Parents should be able to pay online. | Parents pay full or partial instalments through a payment link sent by text message (SMS) or email. Payments post automatically against the correct invoice within one hour and are visible to the campus accountant. Test: make a partial payment and confirm the balance updates on the parent statement. |
| Reports should be available. | The finance manager can view, at any time, outstanding fees by campus, grade and age of debt (0 to 30, 31 to 60, over 60 days), and export the list to Excel. |
| The system must be bilingual. | All parent-facing documents (invoices, statements, receipts, text messages) are available in Arabic and English, with the parent’s preferred language stored in their record. Arabic documents display right to left with correctly ordered numbers and dates. |
The rewritten versions are longer, but each one can be priced, built and tested. A vendor who says yes to these has committed to something specific.
What to include beyond the screens
Functional requirements get most of the attention, but many projects fail on the items around them. A complete requirements document should also cover:
- Data and migration. Which historical data must move to the new system, how many years of it, and who will clean it. State the volumes: number of customers, products, transactions per month.
- Integrations. Every system the new one must exchange data with, the direction of the data, and how often. Examples include the bank, your accounting system, an e-commerce store, or the national e-invoicing system where it applies to you, such as JoFotara in Jordan.
- Users and permissions. How many users per role, what each role may see or change, and which actions need a second person’s approval.
- Reporting. The decisions each report supports, rather than a list of report names.
- Non-functional needs. Expected response times, availability hours, backup and recovery expectations, hosting preferences, and how personal data must be protected. Keep these realistic and specific to your operation.
- Support and handover. Training, documentation, the support hours you need, and what happens if the vendor relationship ends.
Priorities and the process behind them
Mark every requirement as essential, important or nice to have. Be strict. If most items are marked essential, the vendor has no guidance on what can wait. With honest priorities, vendors quote and plan more realistically, and you will have a clear basis for trade-offs when time or budget gets tight.
Write requirements after you understand the process, not before. If the school network has not agreed how discounts are approved across campuses, no requirements document will settle it. The vendor will either build one campus’s habit into the system or ask you to decide in the middle of the project, which is the most expensive moment to do so. Mapping the current process first, as in the Know and Map stages of the KEMLAT Method, turns requirements from guesses into descriptions of how the business will actually run.
Requirements as a shared contract
A good first exercise is to take your ten most important requirements and rewrite each with the five questions above and an acceptance test. If a requirement resists being rewritten, that usually means the process behind it has not been agreed yet, and that is the conversation to have before any vendor meeting.
Requirements analysis and system design are at the core of our Enterprise Systems service. We help you understand the process, write requirements that vendors cannot misread, and select or build a system that fits how you actually work.
