Hand a vendor a requirements document and the first thing they do is look for the words they cannot be held to. Phrases such as user friendly, fast, scalable and easy to integrate appear in most of the documents we read, and they share one problem: nobody can say whether they have been met. That gap between what the business meant and what the supplier agreed to is where most project disputes begin.
This article explains how requirements are actually structured, what makes one testable, and how to build a set that a vendor, a developer or an internal team can be held to. It is the core of the requirements gathering work we do for clients, and it is more technical than it looks.
A requirements document is a promise about the future written in the present tense. When a requirement is vague, every reader fills the gap with their own assumptions. The business assumes one thing. The vendor assumes the cheapest reasonable reading. The developer assumes a third. Nobody notices until acceptance testing, which is the most expensive point to find out.
At that stage the conversation stops being technical and becomes commercial. The vendor says what was delivered matches what was written. The business says it is obviously not what was meant. Both are right, and the only fix is a change request priced at the vendor’s rate. A few extra days of careful writing at the start remove most of that argument.
Business analysts usually separate requirements into layers, and the classification used in the BABOK Guide from the IIBA is a helpful model. Business requirements state why the organisation is doing the work, for example reducing order errors or shortening the monthly close. Stakeholder requirements describe what particular groups need, such as a warehouse lead who must see the picking queue for the day. Solution requirements describe what the system must do, which are the functional requirements, and how well it must do it, which are the non functional requirements. Transition requirements cover what it takes to get from the old way to the new one, including data migration, training and cutover.
Trouble starts when these layers sit in one flat list. A business goal appears next to a button colour, and a data migration task is written as if it were a feature. Reviewers cannot tell what is essential, and nobody can trace a small feature back to the business reason it exists. Keeping the layers separate makes each one easier to write, review and test.
Requirements often arrive as solutions. Someone asks for a dashboard. That sounds like a requirement, but it is a proposed answer to a question that has not been stated. Before writing anything down, ask what decision the dashboard will support, who makes that decision, how often, and what they use today to make it. The answer may be a dashboard. It may equally be a daily email listing the ten orders that are late, which costs a fraction as much to build.
A requirement written as a solution locks the project into one answer and hides the real need. The practical technique is to keep asking why until you reach an outcome someone in the business can measure, and to ask the people who do the work rather than only the manager sponsoring the project. Watching someone perform the task for an hour tells you more than a workshop of ten people describing it.
A testable requirement has an actor, an action, a condition and a measurable result. Compare two versions of the same requirement. The first says search should be fast. The second says a customer service agent can find any order from the last 24 months by order number or customer email, and the result appears within five seconds with 30 people using the system at the same time.
The second version can be estimated by a vendor, tested by a tester and signed off by the business. The first can only be argued about. The IIBA lists acceptance and evaluation criteria as a formal business analysis technique for exactly this reason: they define what done looks like before anyone starts building.
A simple format for acceptance criteria is given, when, then. Given an order exists in the system, when an agent searches by customer email, then the order appears in the results with its status and dispatch date. If you cannot describe how a requirement would be tested, you do not understand it well enough yet, and writing the test is often the quickest way to find out what is missing.
Functional requirements describe features and are usually well covered. Non functional requirements describe qualities such as performance, availability, security, audit trails, data retention and accessibility. They are the ones most often left out, and they are the ones that cause surprises after go live.
A system that works well in a demo with five users can slow badly with forty. A process that nobody thought to log has no audit trail when someone asks who approved a change. For businesses in Ireland and the EU that handle personal data, GDPR obligations such as retention periods, access requests and deletion should be written as requirements, not left to whatever the vendor’s default settings happen to be.
Integration deserves particular care. For every connection to another system, record which system is the source of truth, which direction the data flows, how often it moves, what happens when a transfer fails, and who is told. Integrations that sound simple in a meeting are often where a project doubles in size, because each of those questions has an answer somebody must build.
Take a request that appears in many projects: the system should show order status. Start by asking who needs it and why. Suppose the answer is that customer service agents currently phone the warehouse to ask where an order is, and the business wants to stop that. The business objective is now clear: cut the number of internal status calls.
The stakeholder requirement follows: an agent needs to see the current status of any order while speaking to a customer. The solution requirement then becomes specific. The system shows one of five agreed statuses for each order, updated within two minutes of the warehouse changing it, and an agent can see the time of the last change. The non functional requirement adds that the status view loads within three seconds. The transition requirement notes that the five statuses must be agreed with the warehouse before build, and that agents need a short training session before go live.
Each of these can be tested, each traces back to the reason for doing the work, and none of them says how it should be built. That is the standard to aim for.
There are a handful of problems we see repeatedly. Two teams give requirements that contradict each other, and nobody notices because they were gathered in separate meetings. Requirements describe how something should be built rather than what it must achieve, which limits the vendor’s options and often raises the cost. Requirements have no named owner, so nobody can answer questions about them later. The document is reviewed by managers but never by the people who will use the system. And key assumptions, such as which systems hold the master customer record, are left unwritten because everyone in the room thought they were obvious.
Most of these are easy to catch with a structured review, and they are far cheaper to fix on paper than in a half built system.
A traceability record links each requirement to the business objective it serves, the person who asked for it, its priority and the test that proves it. At the size of a typical mid sized business this can be a single spreadsheet. The value is what it lets you do later.
When scope pressure arrives, you can see which business objective is at risk if something is cut. When someone proposes a new feature, you can ask which objective it serves. You can also spot requirements with no reason attached, which are candidates for removal, and objectives with no requirements against them, which usually mean something has been missed.
The MoSCoW method sorts requirements into must have, should have, could have and will not have this time. It works only if the musts are genuinely limited. A useful test is to ask whether the business could still operate on go live day if this were missing. If the answer is yes, it is not a must.
Record the will not haves as carefully as the rest. Writing down what was deliberately left out prevents the argument three months later about why something was not delivered, and it gives you a ready made list for the next phase.
The costs are familiar. Change requests are priced when the business has the least bargaining power. Development is reworked after features are built on a wrong assumption. Go live slips while a dispute over acceptance is settled. Staff adopt spreadsheets beside the new system because it does not quite fit, and the business pays for the tool and the workaround. It is widely accepted in software delivery that a defect costs more to fix the later it is found, and requirements defects are found later than most.
There is also a procurement cost. Without clear requirements you cannot compare vendor proposals fairly, so the decision drifts toward price and the quality of the demo. That is a poor basis for a contract that may run for years.
We run requirements gathering as a defined piece of work. We interview the right people, map the current process, write requirements with acceptance criteria, resolve the conflicts between teams that always surface, and deliver a signed off requirements pack with traceability that you can hand to any vendor or developer. It is work that needs experience, and for many businesses with 5 to 100 employees it does not justify a permanent hire. That is the gap we fill.
If you have a system, a replacement or a project waiting on requirements nobody has had time to pin down, a free 30 minute consultation is a good way to scope it. You can book one through groowfuse.com.